Florian Weimer <f...@deneb.enyo.de> writes: >>> Duplication is how other GNU projects handle this. For instance, many >>> Emacs Lisp functions are documented twice: once as a docstring in the >>> source code (which is roughly equivalent to the comment-in-spec >>> approach), and once in the Elisp reference (which is GFDLed). >> >> Well probably we can all agree that such duplication is undesirable, >> unless it is automated, since documentation can get out of sync. > > There's a school of thought that claims that things need to be > described at least twice, both formally and informally. I don't think > these people mean "code and documentation", but rather "two forms of > documentation".
With elisp, I've found that in practice I usually start by copying the docstring (the "in code doc") to the manual (the "doc doc"), but almost always end up largely rewriting to fit the context in the manual better, and to explain things in more detail (modern docstrings tend to be rather verbose compared to docstrings-of-old, but they're still generally more terse than the manual). What this says, I dunno; it'd be nice to have the freedom to just do whatever's best, of course... -Miles -- Neighbor, n. One whom we are commanded to love as ourselves, and who does all he knows how to make us disobedient.
