Re: Hello fdclose

On Wednesday, March 19, 2014 12:38:57 am Warren Block wrote:
> On Tue, 18 Mar 2014, John Baldwin wrote:
> 
> > On Monday, March 17, 2014 7:23:19 pm Mariusz Zaborski wrote:
> >> Hi,
> >>
> >> After our previous discuss  [1] I prepare fdclosedir(3) function which
> >> was committed by Pawel (cc'ed) in commit r254499.
> >>
> >> A while ago I also prepare the fdclose function. Unfortunately, this
> >> new function is a little bit more tricky then previous one. Can I ask
> >> you for a review of this patch?
> >
> > I think the code is fine.  I have a few suggestions on the manpage wording:
> >
> > The
> > +.Fn fdclose
> > +function is equivalent to the
> > +.Fn fclose
> > +function except that this function returns file descriptor instead of
> > +closing it.
> > +.Pp
> > +The
> >
> > I would move fdclose() to its own paragraph and reword this sentence as:
> >
> >  "The fdclose() function is equivalent to fclose() except that it does
> >   not close the underlying file descriptor."
> 
> .Fn fdclose
> is equivalent to
> .Fn fclose ,
> but the file descriptor is returned rather than closed.
> 
> Likewise in other sections, the markup is supposed to do the job of 
> pointing out that something is a function.

Yes, but this has the 'no capital letter at the start of a sentence' problem.

Also, I do think reusing the 'underlying file descriptor' language is important
in the context of the earlier description of fclose().

-- 
John Baldwin