This is the mail archive of the gcc@gcc.gnu.org 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


Florian Weimer wrote:
* Robert Dewar:

In the case of interfaces to library routines, what we do
is to have fully commented Ada package specs that act as
both the documentation of the implementation interface and
as the user documentation (for an example, look at g-spipat.ads).
I can't see any value in duplicating this information elsewhere.

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.

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.

The more interesting issue is when the automated documentation does
more than just duplicate, and actually derives information not easily
accessible in the sources.

For example, in the case of the GtkAda documentation,
we actually do generate automatically the GtkAda RM from gtkada spec
files, and there's definitely an added value, since this is not just
a mere duplication: there's extra info (such as type hierarchy info
automatically generated, screenshots, links, ...).

That's the case where the licensing issue is significant. I don't
like the idea of padding out documentation with mere duplication
of code comments (I would rather work on making those comments more
accessible). But when there is additional information generated
automatically, that's a different matter entirely.


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