[RFC] Documenting support functions and data structures

[Manuel López-Ibáñez]

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 
https://gcc.gnu.org/wiki/DocumentationOverviewIssues#Legal_and_Licensing_Issues). 
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.

Cheers,

Manuel.