Re: GFDL/GPL issues

[Joel Sherrill <joel dot sherrill at oarcorp dot com>]

On 08/15/2010 04:09 AM, Florian Weimer wrote:
> * 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".
>    
For RTEMS, that's what we try to do.  There is a User's
manual and the Doxygen generated 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.
>
>    
That's a matter of style and project code style enforcement.
> 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.)
>
>    
So....?  As a user, I don't care how you implemented it.

Really, most of this is largely a matter of the markup and what
is included in the generated documentation.
RTEMS uses Doxygen for C which is probably not the ideal
language for this.  We have guidelines that the .h file always
defines the interface with no details on the implementation.
If there are things that are implementation specific you need
to document, they go in the bodies and are marked as internal
or whatever.

This way you can easily generate "public view" documents
from only the .h files and "augmented" versions with internal
details if you do .h and bodies.

RTEMS is a very old C project which predates Doxygen
by years.  But we believe in specs versus bodies, interfaces
versus implementations, etc.  It was easy to convert our
comments into Doxygen format.

http://www.rtems.org/onlinedocs/doxygen/cpukit/html/index.html

So just because it is possible to do the markup and
generation badly, doesn't mean it isn't possible to
do a good job in any language which supports separate
specs and bodies.

> 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.
>    
And that's unfortunate. :(

--joel
RTEMS