Re: What's an annex? stratum?

Robert Dewar
2007-06-26T18:36:14Z

Markus Deuling wrote:
> Eli Zaretskii wrote:
>
>> That's not surprising: programmers don't like writing documentation as
>> much as they like writing code. That is one reason why gdbint.texinfo
>> is in such poor shape.
>>
>> In any case, if people here believe comments are a reasonable
>> substitute for documentation, perhaps I should from now on reject code
>> patches that do not explain themselves clearly, and do not contain
>> enough references to other related portions of GDB.
>>
>
> Maybe the process of getting a patch into mainline should be changed. Currently a patch without a proper
> Changelog has no chance. Maybe we should extend that and say a patch must have Changelog and one or two
> lines (or even moren) in documentation whenever reasonable.

It's a very important principle that stuff in the changelog is *not* a
substitute for proper documentation in the source. That's a common
mistake (I catch it all the time in the GNAT sources, where all
checkins get reviewed by me with this in mind :-))
>
> For example the guy that wrote the part for inferior function calls definitely wrote no doc :-)
>
> For my opinion GDB's Internal Manual is very important and should be cultivated much more.
>