On Wed, 19 Mar 2014, John Baldwin wrote:

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:

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:

+.Fn fdclose
+function is equivalent to the
+.Fn fclose
+function except that this function returns file descriptor instead of
+closing it.

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.

I've heard that mentioned before, but have never seen any actual rule regarding it. And we do have actual rules about avoiding redundant phrases: http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/book.html#writing-style-guidelines

While normal words should be capitalized as the first word in a sentence, special words that are case-sensitive override that (IMO).

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

Sorry, a problem with my micro-optimization:

.Fn fdclose
is equivalent to
.Fn fclose ,
but does not close the underlying file descriptor.
freebsd-current@freebsd.org mailing list
To unsubscribe, send any mail to "freebsd-current-unsubscr...@freebsd.org"

Reply via email to