This is the mail archive of the gcc@gcc.gnu.org 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: [RFC] Documenting support functions and data structures


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.

They might.

> 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.

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
> wrong?

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
> 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?

Certainly not.

> 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.

Andrew.


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