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
