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.
