Re: [PATCH 01/13] kdbus: add documentation

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

Hello Daniel,

On 01/27/2015 07:14 PM, Daniel Mack wrote:
> Hi Michael,
> 
> On 01/27/2015 06:53 PM, Michael Kerrisk (man-pages) wrote:
>> On 01/27/2015 04:23 PM, David Herrmann wrote:
> 
>>> I only expect a handful of users to call the ioctls directly. The
>>> libraries that implement the payload-marshaling, in particular. It's a
>>> similar situation with netlink.
>>
>> Thanks, David, for the clarification. I think it would have been helpful
>> to have that more clearly stated up front, especially as some comments 
>> in this thread, such as the above, could be interpreted to mean quite 
>> the opposite. Can I suggest that some text on this point be added to 
>> kdbus.txt?
> 
> We're currently working on an a set of comprehensive man pages to
> document all the commands in the API, along with every struct, enum etc.
> We do that so that developers are able to actually understand every
> detail of the API, even though most people - as David explained - will
> not use that interface directly in the first place but let one of the
> high-level libraries help them integrate D-Bus functionality into their
> applications.

(I suggest that some text about this text go into the kdbus(7) page.)

> If you want, have a look at the upstream repository for a 	preliminary
> version of the new docs.

That's at https://code.google.com/p/d-bus/ , right? This looks like a 
good direction to go in. Thanks for tackling that.

I hope to take a longer look sometime soon, but a few general conventions
for man-pages that you might want to consider following:

* When listing errors, I think you should change your 
  language/formatting somewhat. Examples here from kdbus.endpoint.7:
   
  (1) The man page says

          RETURN VALUE
               On success, all mentioned ioctl commands return 0.

       Better to write this from a user-space point of view:

          RETURN VALUE
               On success, all mentioned ioctl commands return 0; on 
               error, -1 is returned, and errno is set to indicate 
               the error.

  (2) I would change the wording in the ERRORS sections from
       "may return the following errors"
       to
       "may fail with the following errors"

  (3) When listing the errors, drop the minus signs; that's not 
      what user-space sees. They see a positive value in errno.

  (4) The usual formatting convention for constants, including 
      error constants in man pages is boldface, rather than 
      underline/emphasis.

  (5) Insofar as it's possible, it would be good to make all
      pages format nicely within 80 columns. Some of the literal
      text and ASCII art could, I think, be narrowed.

Thanks,

Michael
-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/