This is the mail archive of the mailing list for the GCC project.

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: GFDL/GPL issues

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

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. :(


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]