| Message ID | 87hbd6do0r.fsf@mid.deneb.enyo.de |
|---|---|
| State | New |
| Headers | show |
> This almost qualifies as obvious. The style rule is currently > self-contradictory, so it could mean either thing, but I've checked a > few package specs, and the patch below seems to reflect the intended > meaning. > > Okay for mainline? Not OK. As far as I can see, there is no typo (or rather missing word really) there, the comments describing subprogram spec should in general mention and document formal argument names. I'm not sure I understand why you say the style rule is self-contradictory, it's not to me. The part "write a comment that does not depend on the names of things. The names are supplementary, not sufficient, as comments." means that even if a parameter is called e.g. "Is_Open", the spec should make it explicit what this parameter is about. > 2011-01-18 Florian Weimer <fw@deneb.enyo.de> > > * gnat-style.texi (Lexical Elements): Fix typo. > > Index: gnat-style.texi > =================================================================== > > --- gnat-style.texi (revision 168958) > +++ gnat-style.texi (working copy) > @@ -299,7 +299,7 @@ > Descriptions of what subprograms do go with the specification. > > @item > -Comments describing a subprogram spec should specifically mention the > +Comments describing a subprogram spec should not specifically mention the > formal argument names. General rule: write a comment that does not > depend on the names of things. The names are supplementary, not > sufficient, as comments.
>> 2011-01-18 Florian Weimer<fw@deneb.enyo.de> >> >> * gnat-style.texi (Lexical Elements): Fix typo. >> >> Index: gnat-style.texi >> =================================================================== >> >> --- gnat-style.texi (revision 168958) >> +++ gnat-style.texi (working copy) >> @@ -299,7 +299,7 @@ >> Descriptions of what subprograms do go with the specification. >> >> @item >> -Comments describing a subprogram spec should specifically mention the >> +Comments describing a subprogram spec should not specifically mention the >> formal argument names. General rule: write a comment that does not >> depend on the names of things. The names are supplementary, not >> sufficient, as comments. The patch is wrong, you misunderstand the style rule, it is compulsory for the comments to specially mention the formal argument names.
On Jan 19, 2011, at 11:12, Robert Dewar wrote: >>> -Comments describing a subprogram spec should specifically mention the >>> +Comments describing a subprogram spec should not specifically mention the >>> formal argument names. General rule: write a comment that does not >>> depend on the names of things. The names are supplementary, not >>> sufficient, as comments. > > The patch is wrong, you misunderstand the style rule, it is > compulsory for the comments to specially mention the > formal argument names. I agree with Florian that the wording is a bit confusing. Maybe: Comments describing a subprogram spec should specifically mention each formal argument names, but should not depend on the names of arguments to explain their use. Names are supplementary, not sufficient, as description. -Geert
On 1/19/2011 11:22 AM, Geert Bosch wrote: > > On Jan 19, 2011, at 11:12, Robert Dewar wrote: > >>>> -Comments describing a subprogram spec should specifically mention the >>>> +Comments describing a subprogram spec should not specifically mention the >>>> formal argument names. General rule: write a comment that does not >>>> depend on the names of things. The names are supplementary, not >>>> sufficient, as comments. >> >> The patch is wrong, you misunderstand the style rule, it is >> compulsory for the comments to specially mention the >> formal argument names. > > I agree with Florian that the wording is a bit confusing. > > Maybe: > Comments describing a subprogram spec should specifically mention > each formal argument names, but should not depend on the names of > arguments to explain their use. Names are supplementary, not > sufficient, as description. Yes, that's fine, I agree clearer> > -Geert
* Geert Bosch: > On Jan 19, 2011, at 11:12, Robert Dewar wrote: > >>>> -Comments describing a subprogram spec should specifically mention the >>>> +Comments describing a subprogram spec should not specifically mention the >>>> formal argument names. General rule: write a comment that does not >>>> depend on the names of things. The names are supplementary, not >>>> sufficient, as comments. >> >> The patch is wrong, you misunderstand the style rule, it is >> compulsory for the comments to specially mention the >> formal argument names. Maybe, but the sources do not really follow this style consistently (even for a "should" rule). > I agree with Florian that the wording is a bit confusing. > > Maybe: > Comments describing a subprogram spec should specifically mention > each formal argument names, but should not depend on the names of > arguments to explain their use. Names are supplementary, not > sufficient, as description. "each formal argument name", I think. This is much clearer, at least.
Index: gnat-style.texi =================================================================== --- gnat-style.texi (revision 168958) +++ gnat-style.texi (working copy) @@ -299,7 +299,7 @@ Descriptions of what subprograms do go with the specification. @item -Comments describing a subprogram spec should specifically mention the +Comments describing a subprogram spec should not specifically mention the formal argument names. General rule: write a comment that does not depend on the names of things. The names are supplementary, not sufficient, as comments.