[darcs-users] manual/latex vs api docs/haddock
Trent W. Buck
trentbuck at gmail.com
Thu Apr 2 07:24:31 UTC 2009
Simon Michael <simon at joyful.com> writes:
> What should be the guideline for choosing to document either in
> haddock comments, which generate the API docs, or in latex sections,
> which generate the manual ?
1. Is this information useful to end users?
If yes, it goes in the user manual. Often it should also end up in the
manpage and in a "darcs foo --help" string as well.
2. Does this information describe a specific piece of code (e.g. a
function)?
If yes, then obviously it needs to be a haddock comment for that code.
3. Does it describe some general behaviour of Darcs, e.g. the kinds of
primitive patches that exist or how commutation works?
I don't have a good answer here, but I suspect either haddock module
documentation (a "-- |" before the "module" keyword) or, as now, an
appendix of the user manual.
More information about the darcs-users
mailing list