[fpc-pascal] Spreadsheet library/unit?

[Marco van de Voort]

In our previous episode, Felipe Monteiro de Carvalho said:
> > I'm not that fond of in-source docs. It has a certain principal appeal
> > (maintaining both together), but I don't like the practice. Or at least the
> > ones that I have seen.
> 
> I find that the external documentation imposes a too big overhead.
> When in-source I can write it in the same editor I am used to,
> navigating the same source I am used to, instead of an external
> representation of it. Not to mention when things get renamed external
> docs usually have a hard time.
 
I directly agree there is a navigation-to-docs penalty. Even if some
editors/IDEs remedy that, there is a bump there. 

> The external documentation duplicates information, because we already
> describe how things work in the comments, and then we need to describe
> that again in external docs.

No. Only if you insist that all that be in the sources in the first place.
(which is IMHO not the case if there are good external docs). Moreover it
puts yet another pressure on the source files, which already has two
permanent holy wars micromanaging each detail (formatting/identation and
commit/VCS checkout behaviour, maybe the "don't let them be too big" is a
third even) if you are in a team.

If not, the comments in the sources reduce to warn for gotcha's and other
notes, that might not belong in the docs at all. I don't see duplication a
problem if they have two separate purposes. Or better: then it is not
duplication.

> Or if we don't comment properly it becomes hard to underderstand the code.

Also not necesary, to study source, you could have a tool to combine the
source with the external doc, with some crossref data.