This is the mail archive of the
mailing list for the GCC project.
Re: [RFC] Documenting support functions and data structures
- From: Andrew Haley <aph at redhat dot com>
- To: Manuel LÃpez-IbÃÃez <lopezibanez at gmail dot com>, Andrew Haley <"aph at redhat dot com"@redhat.com>
- Cc: Mikhail Maltsev <"maltsevm at gmail dot com"@redhat.com>, gcc mailing list <"gcc at gcc dot gnu dot org"@redhat.com>
- Date: Thu, 16 Apr 2015 16:15:54 +0100
- Subject: Re: [RFC] Documenting support functions and data structures
- Authentication-results: sourceware.org; auth=none
- References: <552F44B1 dot 3090001 at gmail dot com> <552F6CF7 dot 1020401 at redhat dot com> <552FB77C dot 40200 at gmail dot com>
On 04/16/2015 02:22 PM, Manuel LÃpez-IbÃÃez wrote:
> On 16/04/15 10:04, Andrew Haley wrote:
>> On 16/04/15 06:12, Mikhail Maltsev wrote:
>>> So, I want to create a similar page in GCC's internal docs, but I don't
>>> know what should be included (i.e. did I miss something important, or
>>> did I include something obsolete), so I ask for some assistance.
>> The real challenge here is not generating the docs but keeping them in
>> step with the source code. History tells us that this is almost never
>> done well. It's better not to have docs than have wrong docs.
>> If you can find some way to ensure that the docs are always correct
>> (e.g. by structured comments in the source code) that will help.
> I don't buy this argument in general nor in particular for this
> case. In general, because it is much harder to write the docs than
> fixing them. If the docs are wrong at least someone might notice
> that they are and notice the discrepancy.
> If there are no docs, there is no way to even start understanding
> the code. Note that your argument applies also to source code
> comments: There are plenty of outdated comments in GCC's source
Sure, but external docs seem to be less likely to be kept up to date
than internal comments.
> The conclusion would be that no comments are better than some wrong
> comments. Do we want to remove all comments because some might be
No, and this does not follow from what I wrote. It is better to have
no comments than incorrect comments, but this does not imply we should
delete all comments, just incorrect ones.
I did not say "Do not document the structures", I said "Let's try to
make sure the documentation is kept up to date" and suggested a
mechanism by which this might be achieved.
> And yes, I would also be extremely happy if someone figured out a
> way to ensure the docs match the comments. We can probably
> automatically generate from the *.opt files most of invoke.texi and
> even the list of what enables what. But there are significant
> non-technical hurdles to achieve that (See
> Should we say that no updates to invoke.texi are accepted until
> someone implements this automatic generation?
> It does not seem wise to prevent progress (and new contributions)
> simply because the solution is not perfect. It is also not fair to
> dump the hardest more complex problems that no professional
> long-time GCC developer has figured out how to solve on the
> shoulders of new contributors.
That's an excellent point. I withdrew my suggestion that a newcomer
should be trying to solve this problem. I don't want to discourage
anyone from helping.
However, I am advising caution, particularly when documenting
structures whose shape might soon change. And with respect to new
contributions, it would be a shame if someone came along, did a great
job of documenting the structures and interfaces, then left after a
while, leaving the docs to rot.