From mboxrd@z Thu Jan 1 00:00:00 1970 From: Daniel Mack Subject: Re: [PATCH 01/13] kdbus: add documentation Date: Tue, 27 Jan 2015 19:14:11 +0100 Message-ID: <54C7D573.7080809@zonque.org> References: <1421435777-25306-1-git-send-email-gregkh@linuxfoundation.org> <1421435777-25306-2-git-send-email-gregkh@linuxfoundation.org> <54BE5DC8.70706@gmail.com> <54BE9D08.7010804@zonque.org> <54BF805B.4000609@gmail.com> <54BFDAAA.50203@zonque.org> <54C0CE8A.5080805@gmail.com> <20150123155402.GB2159@kroah.com> <54C65267.7090905@gmail.com> <54C66F30.8050108@gmail.com> <54C7D0A3.4000900@gmail.com> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Return-path: In-Reply-To: <54C7D0A3.4000900-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> Sender: linux-api-owner-u79uwXL29TY76Z2rM5mHXA@public.gmane.org To: "Michael Kerrisk (man-pages)" , David Herrmann Cc: Tom Gundersen , Greg Kroah-Hartman , Arnd Bergmann , "Eric W. Biederman" , One Thousand Gnomes , Jiri Kosina , Andy Lutomirski , Linux API , LKML , Djalal Harouni , Johannes Stezenbach , Theodore T'so , christoph Hellwig List-Id: linux-api@vger.kernel.org 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. If you want, have a look at the upstream repository for a preliminary version of the new docs. Thanks, Daniel From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S932697AbbA0SOR (ORCPT ); Tue, 27 Jan 2015 13:14:17 -0500 Received: from svenfoo.org ([82.94.215.22]:58984 "EHLO mail.zonque.de" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S932456AbbA0SOP (ORCPT ); Tue, 27 Jan 2015 13:14:15 -0500 Message-ID: <54C7D573.7080809@zonque.org> Date: Tue, 27 Jan 2015 19:14:11 +0100 From: Daniel Mack User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:31.0) Gecko/20100101 Thunderbird/31.4.0 MIME-Version: 1.0 To: "Michael Kerrisk (man-pages)" , David Herrmann CC: Tom Gundersen , Greg Kroah-Hartman , Arnd Bergmann , "Eric W. Biederman" , One Thousand Gnomes , Jiri Kosina , Andy Lutomirski , Linux API , LKML , Djalal Harouni , Johannes Stezenbach , "Theodore T'so" , christoph Hellwig Subject: Re: [PATCH 01/13] kdbus: add documentation References: <1421435777-25306-1-git-send-email-gregkh@linuxfoundation.org> <1421435777-25306-2-git-send-email-gregkh@linuxfoundation.org> <54BE5DC8.70706@gmail.com> <54BE9D08.7010804@zonque.org> <54BF805B.4000609@gmail.com> <54BFDAAA.50203@zonque.org> <54C0CE8A.5080805@gmail.com> <20150123155402.GB2159@kroah.com> <54C65267.7090905@gmail.com> <54C66F30.8050108@gmail.com> <54C7D0A3.4000900@gmail.com> In-Reply-To: <54C7D0A3.4000900@gmail.com> Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org 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. If you want, have a look at the upstream repository for a preliminary version of the new docs. Thanks, Daniel