This is the mail archive of the
gcc@gcc.gnu.org
mailing list for the GCC project.
Re: GFDL/GPL issues
- From: Florian Weimer <fw at deneb dot enyo dot de>
- To: Joel Sherrill <joel dot sherrill at oarcorp dot com>
- Cc: Robert Dewar <dewar at adacore dot com>, Richard Kenner <kenner at vlsi1 dot ultra dot nyu dot edu>, "mark\ at codesourcery dot com" <mark at codesourcery dot com>, "Joe dot Buck\ at synopsys dot com" <Joe dot Buck at synopsys dot com>, "ams\ at gnu dot org" <ams at gnu dot org>, "bkoz\ at redhat dot com" <bkoz at redhat dot com>, "dnovillo\ at google dot com" <dnovillo at google dot com>, "gcc\ at gcc dot gnu dot org" <gcc at gcc dot gnu dot org>, "iant\ at google dot com" <iant at google dot com>, "richard dot guenther\ at gmail dot com" <richard dot guenther at gmail dot com>, "stevenb dot gcc\ at gmail dot com" <stevenb dot gcc at gmail dot com>
- Date: Sun, 15 Aug 2010 21:12:41 +0200
- Subject: Re: GFDL/GPL issues
- References: <4BFC6EF0.4090908@codesourcery.com> <AANLkTimaPhMzhw66Z6WM+n4dhe1w_ibGFpYExiCym1RC@mail.gmail.com> <AANLkTimZo8PZbrhcghxxaHPyEdW-nExj6VoL25WR3os-@mail.gmail.com> <4C509E54.6090401@codesourcery.com> <AANLkTim+nkpKL9y2kspaWejfOUd9m7xeo6qFUmNJdp8F@mail.gmail.com> <E1OeNjt-0004kn-PY@fencepost.gnu.org> <mcriq3yk7lt.fsf@google.com> <11007291247.AA02219@vlsi1.ultra.nyu.edu> <4C5195FA.2060208@codesourcery.com> <4C52B176.7040807@adacore.com> <4C52E1C0.6090400@codesourcery.com> <4C53696B.7030801@adacore.com> <4C536B50.4010402@codesourcery.com> <AANLkTi=HYhOty0X9E6h7rDhfubFWKOjVstedUAFOCW9O@mail.gmail.com> <11008022335.AA09107@vlsi1.ultra.nyu.edu> <4C575891.1000106@codesourcery.com> <4C5863D6.5090808@adacore.com> <87r5i0s2ic.fsf@mid.deneb.enyo.de> <4C67A8CD.70205@adacore.com> <8739ugs0na.fsf@mid.deneb.enyo.de> <4C6822E0.5020108@oarcorp.com>
* Joel Sherrill:
>> 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.
To my knowledge, the GNU project has no guidelines for the contents of
C header files, and heavy use of the preprocessor is rather common. 8-(
>> 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.
That's precisely my point. Doxygen-style documentation would have to
be attached to an implementation detail, something that the user does
not actually care about.