Re: GFDL/GPL issues

[Florian Weimer <fw at deneb dot enyo dot de>]

* Robert Dewar:

>> 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".

> In the case of the commented Ada specs, there is no point in duplicating
> them in the Ada documentation, since they are accessible easily in an
> appropriate form in the specs.

This approach is far less useful for languages which haven't got
separate spec files because it encourages programmers of client code
to look at the implementation, potentially picking up implementation
details.  It encourages the documentation writer to accidentally refer
to internals, too.

I don't think it works at all for modern C++ code where the surface
syntax of an API is an emerging property.  (The API of foo's type
ensures that "if (foo) { ...}" works as expected, but the exact
language mechanism which achieves that is an implementation detail, so
you can't really attach a docstring to it.)

On the other hand, it is better to generate *some* free documentation,
instead of assuming that programmers will turn to proprietary
documentation which is freely available on the web.