Re: [PATCH 1/2] Documentation/sphinx: kerneldoc: add "unused-functions"

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Am 31.03.2017 um 09:16 schrieb Johannes Berg <johannes@xxxxxxxxxxxxxxxx>:

> From: Johannes Berg <johannes.berg@xxxxxxxxx>
> 
> When adding functions one by one into documentation, in order to
> order/group things properly, it's easy to miss things. Allow use
> of the kernel-doc directive with "unused-functions" like this
> 
> .. kernel-doc:: <filename>
>  :unused-functions:
> 
> to output anything previously unused from that file. This allows
> grouping things but still making sure that the documentation has
> all the functions.

Do we really need such generic stuff? ... IMO explicit is better than
implicit. Why not getting an error when a function, which is referred
from a reST-document disappears in the source? Those errors help
to maintain the consistency of documentation with source-code.

In the past (DocBook) we had such generic stuff and IMO it was not
helpful to serve consistency. Take a look at the old DocBook stuff,
most of it is outdated and some object in the source-code, which are
referred in the past from DocBooks, are no longer existing ... but no
errors when compiling the DocBooks, because these are all generic
includes.

I know, there are also use-cases where generic is very helpful (e.g.
create a complete API description from the header file, with just
one line in reST). And I know, that we have already generic e.g. the
"export" option of the kernel-doc directive.

I'am not totally against generic, but I think every decision in
this direction should be well considered.

These are only my 2cent.

-- Markus --


--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html



[Index of Archives]     [Kernel Newbies]     [Security]     [Netfilter]     [Bugtraq]     [Linux FS]     [Yosemite Forum]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Samba]     [Video 4 Linux]     [Device Mapper]     [Linux Resources]

  Powered by Linux