From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752921AbcHZKTY (ORCPT ); Fri, 26 Aug 2016 06:19:24 -0400 Received: from mga05.intel.com ([192.55.52.43]:34657 "EHLO mga05.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751135AbcHZKTW (ORCPT ); Fri, 26 Aug 2016 06:19:22 -0400 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.28,580,1464678000"; d="scan'208";a="1047602742" From: Jani Nikula To: Mauro Carvalho Chehab , Markus Heiser , "linux-kernel\@vger.kernel.org List" Cc: Jonathan Corbet , linux-doc@vger.kernel.org, Sebastian Reichel Subject: Re: [PATCH 0/3] RFC: The beginning of a proper driver-api book In-Reply-To: <20160826065920.0072c88f@vento.lan> Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo References: <1471899463-5774-1-git-send-email-corbet@lwn.net> <20160823114307.1bf0a3c9@vento.lan> <0464D1F0-1721-4AC2-A7E7-DACDF004F4B9@darmarit.de> <20160826065920.0072c88f@vento.lan> User-Agent: Notmuch/0.22.1+63~g648dcc7 (https://notmuchmail.org) Emacs/24.4.1 (x86_64-pc-linux-gnu) Date: Fri, 26 Aug 2016 13:19:19 +0300 Message-ID: <87poovsuhk.fsf@intel.com> MIME-Version: 1.0 Content-Type: text/plain Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Fri, 26 Aug 2016, Mauro Carvalho Chehab wrote: > Em Fri, 26 Aug 2016 11:34:38 +0200 > Markus Heiser escreveu: > >> Am 23.08.2016 um 16:43 schrieb Mauro Carvalho Chehab : >> >> > Em Mon, 22 Aug 2016 14:57:40 -0600 >> > Jonathan Corbet escreveu: >> > >> >> This short series convers device-drivers.tmpl into the RST format, splits >> >> it up, and sets up the result under Documentation/driver-api/. For added >> >> fun, I've taken one top-level file (hsi.txt) and folded it into the >> >> document as a way of showing the direction I'm thinking I would like things >> >> to go. There is plenty more of this sort of work that could be done, to >> >> say the least - this is just a beginning! >> >> >> >> The formatted results can be seen at: >> >> >> >> http://static.lwn.net/kerneldoc/driver-api/index.html >> > >> > Thanks for doing that! IMHO, the conversion of this book is indeed >> > one of the first things to be done. >> >> >> As part of the long-term task to turn Documentation/ into less of a horror >> >> movie, I'd like to collect documentation of the driver-specific API here. >> >> Hi, >> >> here are my 2cent, about the *generic* content from the kernel-doc >> directive: >> >> .. kernel-doc:: kernel/sched/core.c >> :export: >> >> IMHO directives like the one above are to *generic*. If I read this directive >> I would expect, that all exported symbols are documented. But this is a false >> estimation! >> >> In my POC I use a more restrictive kernel-doc parser >> (https://github.com/return42/linuxdoc). For the directive above the parser >> logs, that some of the exported symbols are not found / not documented: >> >> $ kernel-doc --quiet --list-exports kernel/sched/core.c >> [exported undocumented ] set_cpus_allowed_ptr >> [exported undocumented ] kick_process >> [exported function ] wake_up_process >> [exported undocumented ] preempt_notifier_inc >> [exported undocumented ] preempt_notifier_dec >> [exported function ] preempt_notifier_register >> [exported function ] preempt_notifier_unregister >> [exported undocumented ] single_task_running >> [exported undocumented ] preempt_count_add >> [exported undocumented ] preempt_count_sub >> [exported undocumented ] schedule >> [exported undocumented ] preempt_schedule >> [exported function ] preempt_schedule_notrace >> [exported undocumented ] default_wake_function >> [exported undocumented ] set_user_nice >> [exported function ] sched_setscheduler >> [exported undocumented ] sched_setattr >> [exported function ] sched_setscheduler_nocheck >> [exported undocumented ] _cond_resched >> [exported undocumented ] __cond_resched_lock >> [exported undocumented ] __cond_resched_softirq >> [exported function ] yield >> [exported function ] yield_to >> [exported undocumented ] io_schedule_timeout >> [exported undocumented ] __might_sleep >> [exported undocumented ] ___might_sleep >> >> >> The driver-api is full of *generic* content and IMHO it is not really clear >> what would be a part of the resulting documentation. To illustrate, you >> can take a look on the (old) *automatic* conversion of mine at: >> >> http://return42.github.io/sphkerneldoc/books/device-drivers/index.html >> >> There you see a list of 'Oops: Document generation inconsistency.' >> This kind of missing documentation grows up with changes to >> the source files while there are no errors reported. >> >> What I mean: in most use cases it is better to be explicit and name the >> functions, structs or whatever which should be a part of the documentation. >> e.g.:: >> >> .. kernel-doc:: kernel/sched/core.c >> :functions: wake_up_process yield ... >> >> By being explicit, the kernel-doc parser has a chance to identify requested >> but missing documentation and log related error messages. >> >> Summarized: >> >> - *explicit* is better than implicit. >> - the *generic* part of kernel-doc parser should more restrictive >> >> These are my thoughts, even if we do nothing to handle it, we >> should aware about this. > > I actually prefer the opposite: Ditto. Jani. > > - on a *.c file, it should assume that *all* exported symbols should be > documented (either at the C code itself or at a header file); > > - on a *.h file, it should assume that *all* structs, enums, typedefs, > function prototypes and static inline functions should be documented. > As I stated before, we should also add a way to document defines. > Assuming that we add such way, for defines, it should implicitly > ignore the ones used inside the header to enable/disable part of > its contents, like: > #define _FOO_H_ > #ifndef _FOO_H_ > .... > #endif > > Then, add an option to allow explicitly ignoring symbols. The lack > of documentation for a symbol that matches the above criteria and > isn't explicitly ignored should be warned, as this is a documentation > gap that should be fixed. > > Thanks, > Mauro -- Jani Nikula, Intel Open Source Technology Center