summaryrefslogtreecommitdiff
path: root/scripts/kernel-doc
AgeCommit message (Collapse)AuthorFilesLines
2019-11-07scripts/kernel-doc: Add support for named variable macro argumentsJonathan Neuschäfer1-0/+16
Currently, when kernel-doc encounters a macro with a named variable argument[1], such as this: #define hlist_for_each_entry_rcu(pos, head, member, cond...) ... it expects the variable argument to be documented as `cond...`, rather than `cond`. This is semantically wrong, because the name (as used in the macro body) is actually `cond`. With this patch, kernel-doc will accept the name without dots (`cond` in the example above) in doc comments, and warn if the name with dots (`cond...`) is used and verbose mode[2] is enabled. The support for the `cond...` syntax can be removed later, when the documentation of all such macros has been switched to the new syntax. Testing this patch on top of v5.4-rc6, `make htmldocs` shows a few changes in log output and HTML output: 1) The following warnings[3] are eliminated: ./include/linux/rculist.h:374: warning: Excess function parameter 'cond' description in 'list_for_each_entry_rcu' ./include/linux/rculist.h:651: warning: Excess function parameter 'cond' description in 'hlist_for_each_entry_rcu' 2) For list_for_each_entry_rcu and hlist_for_each_entry_rcu, the correct description is shown 3) Named variable arguments are shown without dots [1]: https://gcc.gnu.org/onlinedocs/cpp/Variadic-Macros.html [2]: scripts/kernel-doc -v [3]: See also https://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu.git/commit/?h=dev&id=5bc4bc0d6153617eabde275285b7b5a8137fdf3c Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net> Tested-by: Paul E. McKenney <paulmck@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-10-01kernel-doc: add support for ____cacheline_aligned_in_smp attributeAndré Almeida1-1/+2
Subroutine dump_struct uses type attributes to check if the struct syntax is valid. Then, it removes all attributes before using it for output. `____cacheline_aligned_in_smp` is an attribute that is not included in both steps. Add it, since it is used by kernel structs. Signed-off-by: André Almeida <andrealmeid@collabora.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-10-01kernel-doc: fix processing nested structs with attributesAndré Almeida1-4/+4
The current regular expression for strip attributes of structs (and for nested ones as well) also removes all whitespaces that may surround the attribute. After that, the code will split structs and iterate for each symbol separated by comma at the end of struct definition (e.g. "} alias1, alias2;"). However, if the nested struct does not have any alias and has an attribute, it will result in a empty string at the closing bracket (e.g "};"). This will make the split return nothing and $newmember will keep uninitialized. Fix that, by ensuring that the attribute substitution will leave at least one whitespace. Signed-off-by: André Almeida <andrealmeid@collabora.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-08-13kernel-doc: Allow anonymous enumAndy Shevchenko1-1/+1
In C is a valid construction to have an anonymous enumerator. Though we have now: drivers/pinctrl/intel/pinctrl-intel.c:240: error: Cannot parse enum! Support it in the kernel-doc script. Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-08-06kernel-doc: ignore __printf attributeRandy Dunlap1-0/+1
Ignore __printf() function attributes just as other __attribute__ strings are ignored. Fixes this kernel-doc warning message: include/kunit/kunit-stream.h:58: warning: Function parameter or member '2' not described in '__printf' Reported-by: kbuild test robot <lkp@intel.com> Signed-off-by: Randy Dunlap <rdunlap@infradead.org> Cc: Brendan Higgins <brendanhiggins@google.com> Tested-by: Brendan Higgins <brendanhiggins@google.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-06-26kernel-doc: Don't try to mark up function namesJonathan Corbet1-1/+1
We now have better automarkup in sphinx itself and, besides, this markup was incorrect and left :c:func: gunk in the processed docs. Sort of discouraging that nobody ever noticed...:) As a first step toward the removal of impenetrable regex magic from kernel-doc it's a tiny one, but you have to start somewhere. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-05-28kernel-doc: always name missing kerneldoc sectionsJonathan Corbet1-7/+9
The "no structured comments found" warning is not particularly useful if there are several invocations, one of which is looking for something wrong. So if something specific has been requested, make it clear that it's the one we weren't able to find. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-01-17kernel-doc: suppress 'not described' warnings for embedded struct fieldsJonathan Corbet1-1/+1
The ability to add kerneldoc comments for fields in embedded structures is useful, but it brought along a whole bunch of warnings for fields that could not be described before. In many cases, there's little value in adding docs for these nested fields, and in cases like: struct a { struct b { int c; } d, e; }; "c" would have to be described twice (as d.c and e.c) to make the warnings go away. We can no doubt do something smarter, but simply suppressing the warnings for this case removes about 70 warnings from the docs build, freeing us to focus on the ones that matter more. So make kerneldoc be silent about missing descriptions for any field containing a ".". Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-11-25scripts/kernel-doc: Fix struct and struct field attribute processingSakari Ailus1-3/+4
The kernel-doc attempts to clear the struct and struct member attributes from the API documentation it produces. It falls short of the job in the following respects: - extra whitespaces are left where __attribute__((...)) was removed, - only a single attribute is removed per struct, - attributes (such as aligned) containing numbers were not removed, - attributes are only cleared from struct fields, not structs themselves. This patch addresses these issues by removing the attributes. Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-11-08kernel-doc: extend $type_param to match members referenced by pointerMike Rapoport1-1/+1
Currently, function parameter description can match '@type.member' expressions but fails to match '@type->member'. Extend the $type_param regex to allow matching both Signed-off-by: Mike Rapoport <rppt@linux.ibm.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-11-08kernel-doc: kill trailing whitespaceMike Rapoport1-2/+2
Signed-off-by: Mike Rapoport <rppt@linux.ibm.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-10-18kernel-doc: fix declaration type determinationRandy Dunlap1-4/+4
Make declaration type determination more robust. When scripts/kernel-doc is deciding if some kernel-doc notation contains an enum, a struct, a union, a typedef, or a function, it does a pattern match on the beginning of the string, looking for a match with one of "struct", "union", "enum", or "typedef", and otherwise defaults to a function declaration type. However, if a function or a function-like macro has a name that begins with "struct" (e.g., struct_size()), then kernel-doc incorrectly decides that this is a struct declaration. Fix this by looking for the declaration type keywords having an ending word boundary (\b), so that "struct_size" will not match a struct declaration. I compared lots of html before/after output from core-api, driver-api, and networking. There were no differences in any of the files that I checked. Signed-off-by: Randy Dunlap <rdunlap@infradead.org> Acked-by: Jani Nikula <jani.nikula@intel.com> Tested-by: Kees Cook <keescook@chromium.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-08-06scripts/kernel-doc: Escape all literal braces in regexesBen Hutchings1-10/+10
Commit 701b3a3c0ac4 ("PATCH scripts/kernel-doc") fixed the two instances of literal braces that Perl 5.28 warns about, but there are still more than it doesn't warn about. Escape all left braces that are treated as literal characters. Also escape literal right braces, for consistency and to avoid confusing bracket-matching in text editors. Signed-off-by: Ben Hutchings <ben@decadent.org.uk> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-07-23PATCH scripts/kernel-docvaldis.kletnieks@vt.edu1-2/+2
Fix a warning whinge from Perl introduced by "scripts: kernel-doc: parse next structs/unions" Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.32), passed through in regex; marked by <-- HERE in m/({ <-- HERE [^\{\}]*})/ at ./scripts/kernel-doc line 1155. Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.32), passed through in regex; marked by <-- HERE in m/({ <-- HERE )/ at ./scripts/kernel-doc line 1179. Signed-off-by: Valdis Kletnieks <valdis.kletnieks@vt.edu> Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-03-30docs: kernel-doc: fix parsing of arraysMauro Carvalho Chehab1-1/+1
The logic with parses array has a bug that prevents it to parse arrays like: struct { ... struct { u64 msdu[IEEE80211_NUM_TIDS + 1]; ... ... Fix the parser to accept it. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-03-21kernel-doc: Remove __sched markingsMatthew Wilcox1-0/+1
I find the __sched annotations unaesthetic in the kernel-doc. Remove them like we remove __inline, __weak, __init and so on. Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-20Merge branch 'kerneldoc2' into docs-nextJonathan Corbet1-301/+365
So once upon a time I set out to fix the problem reported by Tobin wherein a literal block within a kerneldoc comment would be corrupted in processing. On the way, though, I got annoyed at the way I have to learn how kernel-doc works from the beginning every time I tear into it. As a result, seven of the following eight patches just get rid of some dead code and reorganize the rest - mostly turning the 500-line process_file() function into something a bit more rational. Sphinx output is unchanged after these are applied. Then, at the end, there's a tweak to stop messing with literal blocks. If anybody was unaware that I've not done any serious Perl since the 1990's, they will certainly understand that fact now.
2018-02-20docs: Add an SPDX header to kernel-docJonathan Corbet1-0/+1
Add the SPDX header while I'm in the neighborhood. The source itself just says "GNU General Public License", but it also refers people to the COPYING file for further information. Since COPYING says 2.0-only, that is what I have put into the header. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-19scripts: kernel-doc: support in-line comments on nested structs/unionsMauro Carvalho Chehab1-1/+1
The parser at kernel-doc rejects names with dots in the middle. Fix it, in order to support nested structs/unions. Tested-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-19scripts: kernel_doc: fixup reporting of function identifiersMike Rapoport1-1/+1
When function description includes brackets after the function name as suggested by Documentation/doc-guide/kernel-doc, the kernel-doc script omits the function name from "Scanning doc for" report. Extending match for identifier name with optional brackets fixes this issue. Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-15docs: kernel-doc: Don't mangle literal code blocks in commentsJonathan Corbet1-5/+64
It can be useful to put code snippets into kerneldoc comments; that can be done with the "::" operator at the end of a line like this:: if (desperate) run_in_circles(); The ".. code-block::" directive can also be used to this end. kernel-doc currently fails to understand these literal blocks and applies its normal markup to them, which is then treated as literal by sphinx. The result is unsightly markup instead of a useful code snippet. Apply a hack to the output code to recognize literal blocks and avoid performing any special markup on them. It's ugly, but that means it fits in well with the rest of the script. Reviewed-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-15docs: kernel-doc: Finish moving STATE_* code out of process_file()Jonathan Corbet1-62/+77
Move STATE_INLINE and STATE_DOCBLOCK code out of process_file(), which now actually fits on a single screen. Delete an unused variable and add a couple of comments while I'm at it. Reviewed-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-15docs: kernel-doc: Move STATE_PROTO processing into its own functionJonathan Corbet1-18/+28
Move the top-level prototype-processing code out of process_file(). Reviewed-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-15docs: kernel-doc: Move STATE_BODY processing to a separate functionJonathan Corbet1-92/+101
Also group the pseudo-global $leading_space variable with its peers. Reviewed-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-15docs: kernel-doc: Move STATE_NAME processing into its own functionJonathan Corbet1-65/+72
Move this code out of process_file() in the name of readability and maintainability. Reviewed-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-15docs: kernel-doc: Move STATE_NORMAL processing into its own functionJonathan Corbet1-5/+16
Begin the process of splitting up the nearly 500-line process_file() function by moving STATE_NORMAL processing to a separate function. Reviewed-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-15docs: kernel-doc: Rename and split STATE_FIELDJonathan Corbet1-11/+11
STATE_FIELD describes a parser state that can handle any part of a kerneldoc comment body; rename it to STATE_BODY to reflect that. The $in_purpose variable was a hidden substate of STATE_FIELD; get rid of it and make a proper state (STATE_BODY_MAYBE) instead. This will make the subsequent process_file() splitup easier. Reviewed-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-02-15docs: kernel-doc: Get rid of xml_escape() and friendsJonathan Corbet1-56/+9
XML escaping is a worry that came with DocBook, which we no longer have any dealings with. So get rid of the useless xml_escape()/xml_unescape() functions. No change to the generated output. Reviewed-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-01-01scripts: kernel_doc: better handle show warnings logicMauro Carvalho Chehab1-15/+41
The logic with inhibits warnings for definitions that is not output is incomplete: it doesn't cover the cases where OUTPUT_INTERNAL and OUTPUT_EXPORTED are used. As the most common case is OUTPUT_ALL, place it first, in order to optimize a litte bit the check logic. Fixes: 2defb2729217 ("scripts: kernel-doc: apply filtering rules to warnings") Reported-by: Randy Dunlap <rdunlap@infradead.org> Acked-and-Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-21scripts: kernel-doc: apply filtering rules to warningsMauro Carvalho Chehab1-7/+23
When kernel-doc is called with output selection filters, it will be called lots of time for a single file. If there is a warning present there, it means that it may print hundreds of identical warnings. Worse than that, the -function NAME actually filters only functions. So, it makes no sense at all to print warnings for structs or enums. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-21scripts: kernel-doc: improve nested logic to handle multiple identifiersMauro Carvalho Chehab1-25/+44
It is possible to use nested structs like: struct { struct { void *arg1; } st1, st2, *st3, st4; }; Handling it requires to split each parameter. Change the logic to allow such definitions. In order to test the new nested logic, the following file was used to test <code> struct foo { int a; }; /* Just to avoid errors if compiled */ /** * struct my_struct - a struct with nested unions and structs * @arg1: first argument of anonymous union/anonymous struct * @arg2: second argument of anonymous union/anonymous struct * @arg1b: first argument of anonymous union/anonymous struct * @arg2b: second argument of anonymous union/anonymous struct * @arg3: third argument of anonymous union/anonymous struct * @arg4: fourth argument of anonymous union/anonymous struct * @bar.st1.arg1: first argument of struct st1 on union bar * @bar.st1.arg2: second argument of struct st1 on union bar * @bar.st1.bar1: bar1 at st1 * @bar.st1.bar2: bar2 at st1 * @bar.st2.arg1: first argument of struct st2 on union bar * @bar.st2.arg2: second argument of struct st2 on union bar * @bar.st3.arg2: second argument of struct st3 on union bar * @f1: nested function on anonimous union/struct * @bar.st2.f2: nested function on named union/struct */ struct my_struct { /* Anonymous union/struct*/ union { struct { char arg1 : 1; char arg2 : 3; }; struct { int arg1b; int arg2b; }; struct { void *arg3; int arg4; int (*f1)(char foo, int bar); }; }; union { struct { int arg1; int arg2; struct foo bar1, *bar2; } st1; /* bar.st1 is undocumented, cause a warning */ struct { void *arg1; /* bar.st3.arg1 is undocumented, cause a warning */ int arg2; int (*f2)(char foo, int bar); /* bar.st3.fn2 is undocumented, cause a warning */ } st2, st3, *st4; int (*f3)(char foo, int bar); /* f3 is undocumented, cause a warning */ } bar; /* bar is undocumented, cause a warning */ /* private: */ int undoc_privat; /* is undocumented but private, no warning */ /* public: */ int undoc_public; /* is undocumented, cause a warning */ }; </code> It produces the following warnings, as expected: test2.h:57: warning: Function parameter or member 'bar' not described in 'my_struct' test2.h:57: warning: Function parameter or member 'bar.st1' not described in 'my_struct' test2.h:57: warning: Function parameter or member 'bar.st2' not described in 'my_struct' test2.h:57: warning: Function parameter or member 'bar.st3' not described in 'my_struct' test2.h:57: warning: Function parameter or member 'bar.st3.arg1' not described in 'my_struct' test2.h:57: warning: Function parameter or member 'bar.st3.f2' not described in 'my_struct' test2.h:57: warning: Function parameter or member 'bar.st4' not described in 'my_struct' test2.h:57: warning: Function parameter or member 'bar.st4.arg1' not described in 'my_struct' test2.h:57: warning: Function parameter or member 'bar.st4.arg2' not described in 'my_struct' test2.h:57: warning: Function parameter or member 'bar.st4.f2' not described in 'my_struct' test2.h:57: warning: Function parameter or member 'bar.f3' not described in 'my_struct' test2.h:57: warning: Function parameter or member 'undoc_public' not described in 'my_struct' Suggested-by: Markus Heiser <markus.heiser@darmarit.de> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-21scripts: kernel-doc: handle nested struct function argumentsMauro Carvalho Chehab1-12/+26
Function arguments are different than usual ones. So, an special logic is needed in order to handle such arguments on nested structs. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-21scripts: kernel-doc: print the declaration name on warningsMauro Carvalho Chehab1-22/+16
The logic at create_parameterlist()'s ancillary push_parameter() function has already a way to output the declaration name, with would help to discover what declaration is missing. However, currently, the logic is utterly broken, as it uses the var $type with a wrong meaning. With the current code, it will never print anything. I suspect that originally it was using the second argument of output_declaration(). I opted to not rely on a globally defined $declaration_name, but, instead, to pass it explicitly as a parameter. While here, I removed a unaligned check for !$anon_struct_union. This is not needed, as, if $anon_struct_union is not zero, $parameterdescs{$param} will be defined. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-21scripts: kernel-doc: get rid of $nested parameterMauro Carvalho Chehab1-15/+4
The check_sections() function has a $nested parameter, meant to identify when a nested struct is present. As we now have a logic that handles it, get rid of such parameter. Suggested-by: Markus Heiser <markus.heiser@darmarit.de> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-21scripts: kernel-doc: parse next structs/unionsMauro Carvalho Chehab1-53/+68
There are several places within the Kernel tree with nested structs/unions, like this one: struct ingenic_cgu_clk_info { const char *name; enum { CGU_CLK_NONE = 0, CGU_CLK_EXT = BIT(0), CGU_CLK_PLL = BIT(1), CGU_CLK_GATE = BIT(2), CGU_CLK_MUX = BIT(3), CGU_CLK_MUX_GLITCHFREE = BIT(4), CGU_CLK_DIV = BIT(5), CGU_CLK_FIXDIV = BIT(6), CGU_CLK_CUSTOM = BIT(7), } type; int parents[4]; union { struct ingenic_cgu_pll_info pll; struct { struct ingenic_cgu_gate_info gate; struct ingenic_cgu_mux_info mux; struct ingenic_cgu_div_info div; struct ingenic_cgu_fixdiv_info fixdiv; }; struct ingenic_cgu_custom_info custom; }; }; Currently, such struct is documented as: **Definition** :: struct ingenic_cgu_clk_info { const char * name; }; **Members** ``name`` name of the clock With is obvioulsy wrong. It also generates an error: drivers/clk/ingenic/cgu.h:169: warning: No description found for parameter 'enum' However, there's nothing wrong with this kernel-doc markup: everything is documented there. It makes sense to document all fields there. So, add a way for the core to parse those structs. With this patch, all documented fields will properly generate documentation. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-21scripts: kernel-doc: replace tabs by spacesMauro Carvalho Chehab1-5/+5
Sphinx has a hard time dealing with tabs, causing it to misinterpret paragraph continuation. As we're now mainly focused on supporting ReST output, replace tabs by spaces, in order to avoid troubles when the output is parsed by Sphinx. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-21scripts: kernel-doc: change default to ReST formatMauro Carvalho Chehab1-3/+3
Right now, if kernel-doc is called without arguments, it defaults to man pages. IMO, it makes more sense to default to ReST, as this is the output that it is most used nowadays, and it easier to check if everything got parsed fine on an enriched text mode format. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-21scripts: kernel-doc: improve argument handlingMauro Carvalho Chehab1-16/+20
Right now, if one uses "--rst" instead of "-rst", it just ignore the argument and produces a man page. Change the logic to accept both "-cmd" and "--cmd". Also, if "cmd" doesn't exist, print the usage information and exit. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-21scripts: kernel-doc: get rid of unused output formatsMauro Carvalho Chehab1-1179/+4
Since there isn't any docbook code anymore upstream, we can get rid of several output formats: - docbook/xml, html, html5 and list formats were used by the old build system; - As ReST is text, there's not much sense on outputting on a different text format. After this patch, only man and rst output formats are supported. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Acked-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-21docs: get rid of kernel-doc-nano-HOWTO.txtMauro Carvalho Chehab1-1/+1
Everything there is already described at Documentation/doc-guide/kernel-doc.rst. So, there's no reason why to keep it anymore. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-12kernel-doc: parse DECLARE_KFIFO and DECLARE_KFIFO_PTR()Mauro Carvalho Chehab1-2/+6
On media, we now have an struct declared with: struct lirc_fh { struct list_head list; struct rc_dev *rc; int carrier_low; bool send_timeout_reports; DECLARE_KFIFO_PTR(rawir, unsigned int); DECLARE_KFIFO_PTR(scancodes, struct lirc_scancode); wait_queue_head_t wait_poll; u8 send_mode; u8 rec_mode; }; gpiolib.c has a similar declaration with DECLARE_KFIFO(). Currently, those produce the following error: ./include/media/rc-core.h:96: warning: No description found for parameter 'int' ./include/media/rc-core.h:96: warning: No description found for parameter 'lirc_scancode' ./include/media/rc-core.h:96: warning: Excess struct member 'rawir' description in 'lirc_fh' ./include/media/rc-core.h:96: warning: Excess struct member 'scancodes' description in 'lirc_fh' ../drivers/gpio/gpiolib.c:601: warning: No description found for parameter '16' ../drivers/gpio/gpiolib.c:601: warning: Excess struct member 'events' description in 'lineevent_state' So, teach kernel-doc how to parse DECLARE_KFIFO() and DECLARE_KFIFO_PTR(). While here, relax at the past DECLARE_foo() macros, accepting a random number of spaces after comma. The addition of DECLARE_KFIFO() was Suggested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-02scripts/kernel-doc: Don't fail with status != 0 if error encountered with -noneWill Deacon1-1/+1
My bisect scripts starting running into build failures when trying to compile 4.15-rc1 with the builds failing with things like: drivers/net/wireless/broadcom/brcm80211/brcmfmac/sdio.c:2078: error: Cannot parse struct or union! The line in question is actually just a #define, but after some digging it turns out that my scripts pass W=1 and since commit 3a025e1d1c2ea ("Add optional check for bad kernel-doc comments") that results in kernel-doc running on each source file. The file in question has a badly formatted comment immediately before the #define: /** * struct brcmf_skbuff_cb reserves first two bytes in sk_buff::cb for * bus layer usage. */ which causes the regex in dump_struct to fail (lack of braces following struct declaration) and kernel-doc returns 1, which causes the build to fail. Fix the issue by always returning 0 from kernel-doc when invoked with -none. It successfully generates no documentation, and prints out any issues. Cc: Matthew Wilcox <mawilcox@microsoft.com> Cc: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Will Deacon <will.deacon@arm.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-11-24Merge tag 'docs-4.15-2' of git://git.lwn.net/linuxLinus Torvalds1-1/+24
Pull documentation updates from Jonathan Corbet: "A few late-arriving docs updates that have no real reason to wait. There's a new "Co-Developed-by" tag described by Greg, and a build enhancement from Willy to generate docs warnings during a kernel build (but only when additional warnings have been requested in general)" * tag 'docs-4.15-2' of git://git.lwn.net/linux: Add optional check for bad kernel-doc comments Documentation: fix profile= options in kernel-parameters.txt documentation/svga.txt: update outdated file kokr/memory-barriers.txt: Fix typo in paring example kokr/memory-barriers/txt: Replace uses of "transitive" Documentation/process: add Co-Developed-by: tag for patches with multiple authors
2017-11-20Add optional check for bad kernel-doc commentsMatthew Wilcox1-1/+24
Implement a '-none' output mode for kernel-doc which will only output warning messages, and suppresses the warning message about there being no kernel-doc in the file. If the build has requested additional warnings, automatically check all .c files. This patch does not check .h files. Enabling the warning by default would add about 1300 warnings, so it's default off for now. People who care can use this to check they didn't break the docs and maybe we'll get all the warnings fixed and be able to enable this check by default in the future. Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-11-16kmemcheck: rip it outLevin, Alexander (Sasha Levin)1-2/+0
Fix up makefiles, remove references, and git rm kmemcheck. Link: http://lkml.kernel.org/r/20171007030159.22241-4-alexander.levin@verizon.com Signed-off-by: Sasha Levin <alexander.levin@verizon.com> Cc: Steven Rostedt <rostedt@goodmis.org> Cc: Vegard Nossum <vegardno@ifi.uio.no> Cc: Pekka Enberg <penberg@kernel.org> Cc: Michal Hocko <mhocko@kernel.org> Cc: Eric W. Biederman <ebiederm@xmission.com> Cc: Alexander Potapenko <glider@google.com> Cc: Tim Hansen <devtimhansen@gmail.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2017-09-27scripts/kernel-doc: warn on excess enum value descriptionsJohannes Berg1-4/+13
The existing message "Excess struct/union/enum/typedef member [...]" made it sound like this would already be done, but the code is never invoked for enums or typedefs (and really can't be). Add some code to the enum dumper to handle this there instead. While at it, also make the above message more accurate by simply dumping the type that was passed in, and pass the struct/union differentiation in. Signed-off-by: Johannes Berg <johannes.berg@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-08-31kernel-doc parser mishandles declarations split into linesMarkus Heiser1-0/+4
Reported by Johannes Berg [1]. Problem here: function process_proto_type() concatenates the striped lines of declaration without any whitespace. A one-liner of:: struct something { struct foo bar; }; has to be:: struct something {struct foo bar;}; Without the patching process_proto_type(), the result missed the space between 'foo' and 'bar':: struct something {struct foobar;}; Bugfix of process_proto_type() brings next error when blank lines between enum declaration:: warning: Enum value ' ' not described in enum 'foo' Problem here: dump_enum() does not strip leading whitespaces from the concatenated string (with the new additional space from process_proto_type). [1] https://www.mail-archive.com/linux-doc@vger.kernel.org/msg12410.html Signed-off-by: Markus Heiser <markus.heiser@darmarit.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-07-08Merge tag 'kbuild-misc-v4.13' of ↵Linus Torvalds1-1/+2
git://git.kernel.org/pub/scm/linux/kernel/git/masahiroy/linux-kbuild Pull misc Kbuild updates from Masahiro Yamada: - Use more portable shebang for Perl scripts - Remove trailing spaces from GCC version in kernel log - Make initramfs generation deterministic * tag 'kbuild-misc-v4.13' of git://git.kernel.org/pub/scm/linux/kernel/git/masahiroy/linux-kbuild: kbuild: create deterministic initramfs directory listings scripts/mkcompile_h: Remove trailing spaces from compiler version scripts: Switch to more portable Perl shebang
2017-07-03scripts/kernel-doc: handle DECLARE_HASHTABLEJakub Kicinski1-0/+2
DECLARE_HASHTABLE needs similar handling to DECLARE_BITMAP because otherwise kernel-doc assumes the member name is the second, not first macro parameter. Signed-off-by: Jakub Kicinski <jakub.kicinski@netronome.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-05-14scripts: Switch to more portable Perl shebangKamil Rytarowski1-1/+2
The default NetBSD package manager is pkgsrc and it installs Perl along other third party programs under custom and configurable prefix. The default prefix for binary prebuilt packages is /usr/pkg, and the Perl executable lands in /usr/pkg/bin/perl. This change switches "/usr/bin/perl" to "/usr/bin/env perl" as it's the most portable solution that should work for almost everybody. Perl's executable is detected automatically. This change switches -w option passed to the executable with more modern "use warnings;" approach. There is no functional change to the default behavior. While there, drop "require 5" from scripts/namespace.pl (Perl from 1994?). Signed-off-by: Kamil Rytarowski <n54@gmx.com> Signed-off-by: Masahiro Yamada <yamada.masahiro@socionext.com>