[gambit-list] Truck-Factor by mtov
Hendrik Boom
hendrik at topoi.pooq.com
Fri Jul 24 12:56:59 EDT 2015
On Thu, Jul 23, 2015 at 10:58:13PM -0400, William Soukoreff wrote:
>
> What would have the most impact - commenting inside the source code, or external
> documentation (perhaps a wiki), or something hybrid, like encoded comments inside
> the source code that could be "compiled" to viewable comments, similar to, for
> example, Javadocs)?
Whatever is used, it should be something that can be compiled to an elegant
document.
The documentation source code should be edited as plain ASCII or UTF-8 text
No trivial layout changes such as changing line boundarise to make it look
pretty should be made in the source code -- this kind of thing, though it looks good,
does not play well with revision control.
Markdown is popular for this. Asciidoc is possibly better because it is designed for
making books rather than blog entries. Scribble (from the Racket project) has the
advantage of being Scheme-based, so it's possible to write Scheme programs to
produce text where appropriate.
Note that Scribble-based documentation might fit well into Scheme source code,
especially if there were some mechanism to filter it in or out of a partiular
execution or compilation.
-- hendrik
More information about the Gambit-list
mailing list