This is the mail archive of the
mailing list for the GCC project.
Re: Re: [RFC] Documenting support functions and data structures
- From: Manuel LÃpez-IbÃÃez <lopezibanez at gmail dot com>
- To: Andrew Haley <"aph at redhat dot com">
- Cc: Mikhail Maltsev <"maltsevm at gmail dot com">, gcc mailing list <"gcc at gcc dot gnu dot org">
- Date: Thu, 16 Apr 2015 15:22:04 +0200
- Subject: Re: 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>
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 code. The conclusion would be
that no comments are better than some wrong comments. Do we want to remove all
comments because some might be wrong?
In particular in this case, he is basically creating an index of fundamental
data structures in GCC. The index can briefly summarize the data structures,
but it can also simply point out to comments in the code for more info. I would
consider a positive step even if just the draft above was texified and added to
gccint (after appropriate fixes).
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.