[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