My name is Adam. This year, I participate in Google Summer of Code. I wrote manual page for my API. I would be thankful if you could take a look at it.
Thanks in advance!
Unit Tests Skipped
This is an if/then sentence, which is halting when read. Swap it around and edit a bit:
The concept of cookies is explained in
Needs an ending period:
.Xr nv 9 .
"allows to" is not something generally said.
family of functions obtains the value of the supplied cookie.
These appear to be copies of the dnvlist man page, so I would suggest waiting for that one and using that wording.
Needs a serial comma after "binaries" to separate it from "arrays":
Returned strings, nvlists, descriptors, binaries, or arrays must not be modified
"in *an* error state."
The sentence ends on the previous line, so this line should be removed.
As above, change from "nvlist_destroy function." to "nvlist_destroy.":
.Fn nvlist_destroy .
and delete the next line,
family of functions removes an element of the supplied cookie and frees all resources
(This has been said in this or the other related man page, possibly more clearly. It might be better to copy that one.)
s/If element/If an element/
It seems a bit strange to refer to close(2) and free(3) from a section 9 (kernel) man page since those functions cannot be called from the kernel. The nv(9) man page already in -current seems to have the same problem. Ideally, the man page would describe the differences between the kernel and userland versions of the APIs.
"the value associated with the given cookie" like below may be clearer.
It may be clearer to write "must not be modified by the user, since they still belong to the nvlist."
the returned memory
What is an "element of the supplied cookie"?
This should be EXAMPLE (capitals).
Needs an "and"
.Fn nvlist_get_parent , and
s/with the/with/ --just "with close(2)."
Please avoid "the following", and just use "this". Also, add "the" to "the cnvlist API":
This example demonstrates how to deal with the cnvlist API.
These should be sorted by section number then name. So:
.Xr close 2 , .Xr free 3 , .Xr nv 9