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: Re: [RFC] Documenting support functions and data structures

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.



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