summaryrefslogtreecommitdiffstats
path: root/scripts/kernel-doc (follow)
Commit message (Collapse)AuthorAgeFilesLines
* kernel-doc parser mishandles declarations split into linesMarkus Heiser2017-08-311-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>
* Merge tag 'kbuild-misc-v4.13' of ↵Linus Torvalds2017-07-081-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
| * scripts: Switch to more portable Perl shebangKamil Rytarowski2017-05-141-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>
* | scripts/kernel-doc: handle DECLARE_HASHTABLEJakub Kicinski2017-07-031-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>
* scripts/kernel-doc: fix handling of parameters with parenthesisMauro Carvalho Chehab2017-04-021-4/+3
| | | | | | | | | | | | | | | lib/crc32c defines one parameter as: const u32 (*tab)[256] Better handle parenthesis, to avoid those warnings: ./lib/crc32.c:149: warning: No description found for parameter 'tab)[256]' ./lib/crc32.c:149: warning: Excess function parameter 'tab' description in 'crc32_le_generic' ./lib/crc32.c:294: warning: No description found for parameter 'tab)[256]' ./lib/crc32.c:294: warning: Excess function parameter 'tab' description in 'crc32_be_generic' Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* scripts/kernel-doc: fix parser for apostrophesMauro Carvalho Chehab2017-04-021-1/+11
| | | | | | | | | | | On ReST, adding a text like ``literal`` is valid. However, the kernel-doc script won't handle it fine. We really need this feature, in order to escape things like %ph, with is found on some C files. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* kernel-doc: Handle returning pointers to pointersMatthew Wilcox2017-01-261-7/+7
| | | | | | | | | | | | | | | | Clearly nobody ever tried to build the documentation for the radix tree before: include/linux/radix-tree.h:400: warning: cannot understand function prototype: 'void ** radix_tree_iter_init(struct radix_tree_iter *iter, unsigned long start) ' Indeed, the regexes only handled a single '*', not one-or-more. I have tried to fix that, but now I have perl regexes all over my hands, and I fear I shall never be clean again. Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* kernel-doc: properly document array arguments of functionGabriel Krisman Bertazi2017-01-131-1/+1
| | | | | | | | | | | | | | | | | Documentation for array parameters passed in a function, like the first argument in the function below, weren't getting exported in the rst format, although they work fine for html and pdf formats: void drm_clflush_pages(struct page * pages[], unsigned long num_pages) That's because the string key to store the description in the parameterdescs dictionary doesn't have the [] suffix. This cleans up the suffix from the key before accessing the dictionary. Signed-off-by: Gabriel Krisman Bertazi <krisman@collabora.co.uk> Fixes: c0d1b6ee780a ("kernel-doc: produce RestructuredText output") Reviewed-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* kernel-doc: make highlights more homogenous for the various backendsPaolo Bonzini2017-01-041-18/+50
| | | | | | | | | | | | | | | | | | | $type_struct_full and friends are only used by the restructuredText backend, because it needs to separate enum/struct/typedef/union from the name of the type. However, $type_struct is *also* used by the rST backend. This is confusing. This patch replaces $type_struct's use in the rST backend with a new $type_fallback; it modifies $type_struct so that it can be used in the rST backend; and creates regular expressions like $type_struct for enum/typedef/union, for use in all backends. Note that, compared to $type_*_full, in the new regexes $1 includes both the "kind" and the name (before, $1 was pretty much a constant). Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Acked-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* kernel-doc: make member highlighting available in all backendsPaolo Bonzini2017-01-041-11/+19
| | | | | | | | | | | | | | Note that, in order to produce the correct Docbook markup, the "." or "->" must be separated from the member name in the regex's captured fields. For consistency, this change is applied to $type_member and $type_member_func too, not just to $type_member_xml. List mode only prints the struct name, to avoid any undesired change in the operation of docproc. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Acked-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* kernel-doc: include parameter type in docbook outputPaolo Bonzini2017-01-041-2/+4
| | | | | | | | | | The restructuredText output includes both the parameter type and the name for functions and function-typed members. Do the same for docbook. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Acked-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* kernel-doc: strip attributes even if they have an argumentPaolo Bonzini2017-01-041-1/+7
| | | | | | | | | | | | | | | | An inline function can have an attribute, as in include/linux/log2.h, and kernel-doc handles this already for simple cases. However, some attributes have arguments (e.g. the "target" attribute). Handle those too. Furthermore, attributes could be at the beginning of a function declaration, before the return type. To correctly handle this case, you need to strip spaces after the attributes; otherwise, dump_function is left confused. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Acked-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* kernel-doc: cleanup parameter type in function-typed argumentsPaolo Bonzini2017-01-041-0/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | | | A prototype like /** * foo - sample definition * @bar: a parameter */ int foo(int (*bar)(int x, int y)); is currently producing .. c:function:: int foo (int (*bar) (int x, int y) sample definition **Parameters** ``int (*)(int x, int y) bar`` a parameter Collapse the spaces so that the output is nicer. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Acked-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* kernel-doc: add support for one line inline struct member doc commentsJani Nikula2016-11-171-1/+11
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | kernel-doc supports documenting struct members "inline" since a4c6ebede2f9 ("scripts/kernel-doc Allow struct arguments documentation in struct body"). This requires the inline kernel-doc comments to have the opening and closing comment markers (/** and */ respectively) on lines of their own, even for short comments. For example: /** * struct foo - struct documentation */ struct foo { /** * @bar: member documentation */ int bar; }; Add support for one line inline comments: /** * struct foo - struct documentation */ struct foo { /** @bar: member documentation */ int bar; }; Note that mixing of the two in one doc comment is not allowed; either both comment markers must be on lines of their own, or both must be on the one line. This limitation keeps both the comments more uniform, and kernel-doc less complicated. Cc: Daniel Vetter <daniel@ffwll.ch> Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* kernel-doc: better parsing of named variable argumentsSilvio Fricke2016-10-281-2/+6
| | | | | | | | | | | Without this patch we get warnings for named variable arguments. warning: No description found for parameter '...' warning: Excess function parameter 'args' description in 'alloc_ordered_workqueue' Signed-off-by: Silvio Fricke <silvio.fricke@gmail.com> Reviewed-by: Jani Nikula <jani.nikula@intel.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: Special-case function-pointer parameters in kernel-docJonathan Corbet2016-09-061-0/+2
| | | | | | | Add yet another regex to kernel-doc to trap @param() references separately and not produce corrupt RST markup. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: make kernel-doc handle varargs properlyJonathan Corbet2016-09-061-1/+2
| | | | | | | | | | As far as I can tell, the handling of "..." arguments has never worked right, so any documentation provided was ignored in favor of "variable arguments." This makes kernel-doc handle "@...:" as documented. It does *not* fix spots in kerneldoc comments that don't follow that convention, but they are no more broken than before. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs-rst: kernel-doc: fix typedef output in RST formatMauro Carvalho Chehab2016-09-011-10/+24
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | When using a typedef function like this one: typedef bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle); The Sphinx C domain expects it to create a c:type: reference, as that's the way it creates the type references when parsing a c:function:: declaration. So, a declaration like: .. c:function:: bool v4l2_valid_dv_timings (const struct v4l2_dv_timings * t, const struct v4l2_dv_timings_cap * cap, v4l2_check_dv_timings_fnc fnc, void * fnc_handle) Will create a cross reference for :c:type:`v4l2_check_dv_timings_fnc`. So, when outputting such typedefs in RST format, we need to handle this special case, as otherwise it will produce those warnings: ./include/media/v4l2-dv-timings.h:43: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc ./include/media/v4l2-dv-timings.h:60: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc ./include/media/v4l2-dv-timings.h:81: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc So, change the kernel-doc script to produce a RST output for the above typedef as: .. c:type:: v4l2_check_dv_timings_fnc **Typedef**: timings check callback **Syntax** ``bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle);`` Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs-rst: improve typedef parserMauro Carvalho Chehab2016-09-011-1/+3
| | | | | | | | | Improve the parser to handle typedefs like: typedef bool v4l2_check_dv_timings_fnc(const struct v4l2_dv_timings *t, void *handle); Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs-rst: kernel-doc: better output struct membersMauro Carvalho Chehab2016-08-241-1/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Right now, for a struct, kernel-doc produces the following output: .. c:type:: struct v4l2_prio_state stores the priority states **Definition** :: struct v4l2_prio_state { atomic_t prios[4]; }; **Members** ``atomic_t prios[4]`` array with elements to store the array priorities Putting a member name in verbatim and adding a continuation line causes the LaTeX output to generate something like: item[atomic_t prios\[4\]] array with elements to store the array priorities Everything inside "item" is non-breakable, with may produce lines bigger than the column width. Also, for function members, like: int (* rx_read) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num); It puts the name of the member at the end, like: int (*) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num) read With is very confusing. The best is to highlight what really matters: the member name. is a secondary information. So, change kernel-doc, for it to produce the output on a different way: **Members** ``prios[4]`` array with elements to store the array priorities Also, as the type is not part of LaTeX "item[]", LaTeX will split it into multiple lines, if needed. So, both LaTeX/PDF and HTML outputs will look good. It should be noticed, however, that the way Sphinx LaTeX output handles things like: Foo bar is different than the HTML output. On HTML, it will produce something like: **Foo** bar While, on LaTeX, it puts both foo and bar at the same line, like: **Foo** bar Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* doc-rst: Revert "kernel-doc: fix handling of address_space tags"Markus Heiser2016-08-221-3/+0
| | | | | | | | | | | | | | | | This reverts commit a88b1672d4ddf9895eb53e6980926d5e960dea8e. From the origin comit log:: The RST cpp:function handler is very pedantic: it doesn't allow any macros like __user on it Since the kernel-doc parser does NOT make use of the cpp:domain, there is no need to change the kernel-doc parser eleminating the address_space tags. Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* doc-rst: kernel-doc: fix handling of address_space tagsMauro Carvalho Chehab2016-07-221-0/+4
| | | | | | | | | | | | | | | | | | | | | | | | | | | The RST cpp:function handler is very pedantic: it doesn't allow any macros like __user on it: Documentation/media/kapi/dtv-core.rst:28: WARNING: Error when parsing function declaration. If the function has no return type: Error in declarator or parameters and qualifiers Invalid definition: Expecting "(" in parameters_and_qualifiers. [error at 8] ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len) --------^ If the function has a return type: Error in declarator or parameters and qualifiers If pointer to member declarator: Invalid definition: Expected '::' in pointer to member (function). [error at 37] ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len) -------------------------------------^ If declarator-id: Invalid definition: Expecting "," or ")" in parameters_and_qualifiers, got "*". [error at 102] ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len) ------------------------------------------------------------------------------------------------------^ So, we have to remove it from the function prototype. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* kernel-doc: Fix up warning outputDaniel Vetter2016-07-181-1/+1
| | | | | | | | | | | | While trying to make gpu docs warning free I stumbled over one output which wasn't following proper compiler error output standards. Fix it up for more quickfix awesomeness. Cc: Jonathan Corbet <corbet@lwn.net> Cc: Jani Nikula <jani.nikula@intel.com> Cc: linux-doc@vger.kernel.org Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* kernel-doc: unify all EXPORT_SYMBOL scanning to one placeJani Nikula2016-06-101-13/+5
| | | | | | | Scan all input files for EXPORT_SYMBOLs along with the explicitly specified export files before actually parsing anything. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
* kernel-doc: add support for specifying extra files for EXPORT_SYMBOLsJani Nikula2016-06-101-2/+37
| | | | | | | | | | | | | | | | | | | If the kernel-doc comments for functions are not in the same file as the EXPORT_SYMBOL statements, the -export and -internal output selections do not work as expected. This is typically the case when the kernel-doc comments are in header files next to the function declarations and the EXPORT_SYMBOL statements are next to the function definitions in the source files. Let the user specify additional source files in which to look for the EXPORT_SYMBOLs using the new -export-file FILE option, which may be given multiple times. The pathological example for this is include/net/mac80211.h, which has all the kernel-doc documentation for the exported functions defined in a plethora of source files net/mac80211/*.c. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
* kernel-doc: abstract filename mappingJani Nikula2016-06-101-9/+18
| | | | | | Reduce duplication in follow-up work. No functional changes. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
* kernel-doc: add missing semi-colons in option parsingJani Nikula2016-06-101-2/+2
| | | | Signed-off-by: Jani Nikula <jani.nikula@intel.com>
* kernel-doc: do not warn about duplicate default section namesJani Nikula2016-06-101-2/+5
| | | | | | | | | | | | | | | | | | | | | | | | | Since commit 32217761ee9db0215350dfe1ca4e66f312fb8c54 Author: Jani Nikula <jani.nikula@intel.com> Date: Sun May 29 09:40:44 2016 +0300 kernel-doc: concatenate contents of colliding sections we started getting (more) errors on duplicate section names, especially on the default section name "Description": include/net/mac80211.h:3174: warning: duplicate section name 'Description' This is usually caused by a slightly unorthodox placement of parameter descriptions, like in the above case, and kernel-doc resetting back to the default section more than once within a kernel-doc comment. Ignore warnings on the duplicate section name automatically assigned by kernel-doc, and only consider explicitly user assigned duplicate section names an issue. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
* kernel-doc: remove old debug cruft from dump_section()Jani Nikula2016-06-101-3/+0
| | | | | | No functional changes. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
* docs: kernel-doc: Add "example" and "note" to the magic section typesJonathan Corbet2016-06-091-1/+2
| | | | | | | | Lots of kerneldoc entries use "example:" or "note:" as section headers. Until such a time as we can make them use proper markup, make them work as intended. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* scripts/kernel-doc: Add option to inject line numbersDaniel Vetter2016-06-041-0/+41
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Opt-in since this wreaks the rst output and must be removed by consumers again. This is useful to adjust the linenumbers for included kernel-doc snippets in shinx. With that sphinx error message will be accurate when there's issues with the rst-ness of the kernel-doc comments. Especially when transitioning a new docbook .tmpl to .rst this is extremely useful, since you can just use your editors compilation quickfix list to accurately jump from error to error. v2: - Also make sure that we filter the LINENO for purpose/at declaration start so it only shows for selected blocks, not all of them (Jani). While at it make it a notch more accurate. - Avoid undefined $lineno issues. I tried filtering these out at the callsite, but Jani spotted more when linting the entire kernel. Unamed unions and similar things aren't stored consistently and end up with an undefined line number (but also no kernel-doc text, just the parameter type). Simplify things and filter undefined line numbers in print_lineno() to catch them all. v3: Fix LINENO 0 issue for kernel-doc comments without @param: lines or any other special sections that directly jump to the description after the "name - purpose" line. Only really possible for functions without parameters. Noticed by Jani. Cc: Jani Nikula <jani.nikula@intel.com> Cc: linux-doc@vger.kernel.org Cc: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
* scripts/kernel-doc: Also give functions symbolic namesDaniel Vetter2016-06-031-4/+4
| | | | | | | | | | state3 = prototype parsing, so name them accordingly. Cc: Jani Nikula <jani.nikula@intel.com> Cc: linux-doc@vger.kernel.org Cc: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
* scripts/kernel-doc: Remove duplicated DOC: start handlingDaniel Vetter2016-06-031-18/+1
| | | | | | | | | | | | | | | | | | | | | | | | | Further up in the state machinery we switch from STATE_NAME to STATE_DOCBLOCK when we match /$doc_block/. Which means this block of code here is entirely unreachable, unless there are multiple DOC: sections within a single kernel-doc comment. Getting a list of all the files with more than one DOC: section using $ git grep -c " * DOC:" | grep -v ":1$" and then doing a full audit of them reveals there are no such comment blocks in the kernel. Supporting multiple DOC: sections in a single kernel-doc comment does not seem like a recommended way of doing things anyway, so nuke the code for simplicity. Cc: Jani Nikula <jani.nikula@intel.com> Cc: linux-doc@vger.kernel.org Cc: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch> [Jani: amended the commit message] Signed-off-by: Jani Nikula <jani.nikula@intel.com>
* kernel-doc: reset contents and section harderJani Nikula2016-05-301-0/+3
| | | | | | | If the documentation comment does not have params or sections, the section heading may leak from the previous documentation comment. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
* kernel-doc: concatenate contents of colliding sectionsJani Nikula2016-05-301-4/+6
| | | | | | | | | | | | | | | | | | | If there are multiple sections with the same section name, the current implementation results in several sections by the same heading, with the content duplicated from the last section to all. Even if there's the error message, a more graceful approach is to combine all the identically named sections into one, with concatenated contents. With the supported sections already limited to select few, there are massively fewer collisions than there used to be, but this is still useful for e.g. when function parameters are documented in the middle of a documentation comment, with description spread out above and below. (This is not a recommended documentation style, but used in the kernel nonetheless.) We can now also demote the error to a warning. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
* kernel-doc: limit the "section header:" detection to a select fewJani Nikula2016-05-301-2/+17
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | kernel-doc currently identifies anything matching "section header:" (specifically a string of word characters and spaces followed by a colon) as a new section in the documentation comment, and renders the section header accordingly. Unfortunately, this turns all uses of colon into sections, mostly unintentionally. Considering the output, erroneously creating sections when not intended is always worse than erroneously not creating sections when intended. For example, a line with "http://example.com" turns into a "http" heading followed by "//example.com" in normal text style, which is quite ugly. OTOH, "WARNING: Beware of the Leopard" is just fine even if "WARNING" does not turn into a heading. It is virtually impossible to change all the kernel-doc comments, either way. The compromise is to pick the most commonly used and depended on section headers (with variants) and accept them as section headers. The accepted section headers are, case insensitive: * description: * context: * return: * returns: Additionally, case sensitive: * @return: All of the above are commonly used in the kernel-doc comments, and will result in worse output if not identified as section headers. Also, kernel-doc already has some special handling for all of them, so there's nothing particularly controversial in adding more special treatment for them. While at it, improve the whitespace handling surrounding section names. Do not consider the whitespace as part of the name. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
* kernel-doc/rst: remove fixme commentJani Nikula2016-05-301-1/+0
| | | | | | Yes, for our purposes the type should contain typedef. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
* kernel-doc/rst: use *undescribed* instead of _undescribed_Jani Nikula2016-05-301-2/+2
| | | | | | The latter isn't special to rst. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
* kernel-doc: strip leading whitespace from continued param descsJani Nikula2016-05-301-1/+15
| | | | | | | | | | | | If a param description spans multiple lines, check any leading whitespace in the first continuation line, and remove same amount of whitespace from following lines. This allows indentation in the multi-line parameter descriptions for aesthetical reasons while not causing accidentally significant indentation in the rst output. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
* kernel-doc: improve handling of whitespace on the first line param descriptionJani Nikula2016-05-301-4/+4
| | | | | | | | | Handle whitespace on the first line of param text as if it was the empty string. There is no need to add the newline in this case. This improves the rst output in particular, where blank lines may be problematic in parameter lists. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
* kernel-doc/rst: change the output layoutJani Nikula2016-05-301-17/+17
| | | | | | | | | | | | | | | | Move away from field lists, and simply use **strong emphasis** for section headings on lines of their own. Do not use rst section headings, because their nesting depth depends on the surrounding context, which kernel-doc has no knowledge of. Also, they do not need to end up in any table of contexts or indexes. There are two related immediate benefits. Field lists are typically rendered in two columns, while the new style uses the horizontal width better. With no extra indent on the left, there's no need to be as fussy about it. Field lists are more susceptible to indentation problems than the new style. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
* kernel-doc: strip leading blank lines from inline doc commentsJani Nikula2016-05-301-0/+4
| | | | | | | | The inline member markup allows whitespace lines before the actual documentation starts. Strip the leading blank lines. This improves the rst output. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
* kernel-doc/rst: blank lines in output are not neededJani Nikula2016-05-301-6/+1
| | | | | | Current approach leads to two blank lines, while one is enough. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
* kernel-doc: fix wrong code indentationJani Nikula2016-05-301-1/+1
| | | | | | No functional changes. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
* kernel-doc: do not regard $, %, or & prefixes as special in section namesJani Nikula2016-05-301-12/+2
| | | | | | | | | | | | The use of these is confusing in the script, and per this grep, they're not used anywhere anyway: $ git grep " \* [%$&][a-zA-Z0-9_]*:" -- *.[ch] | grep -v "\$\(Id\|Revision\|Date\)" While at it, throw out the constants array, nothing is ever put there again. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
* kernel-doc/rst: highlight function/struct/enum purpose lines tooJani Nikula2016-05-301-12/+25
| | | | | | | Let the user use @foo, &bar, %baz, etc. in the first kernel-doc purpose line too. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
* kernel-doc/rst: drop redundant unescape in highlightingJani Nikula2016-05-301-1/+0
| | | | | | This bit is already done by xml_unescape() above. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
* kernel-doc/rst: add support for struct/union/enum member referencesJani Nikula2016-05-301-0/+5
| | | | | | | | | Link "&foo->bar", "&foo->bar()", "&foo.bar", and "&foo.bar()" to the struct/union/enum foo definition. The members themselves do not currently have anchors to link to, but this is better than nothing, and promotes a universal notation. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
* kernel-doc/rst: add support for &union foo and &typedef foo referencesJani Nikula2016-05-301-0/+4
| | | | | | | | | Let the user use "&union foo" and "&typedef foo" to reference foo. The difference to using "union &foo", "typedef &foo", or just "&foo" (which are valid too) is that "union" and "typedef" become part of the link text. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
* kernel-doc/rst: &foo references are more universal than structsJani Nikula2016-05-301-1/+2
| | | | | | | It's possible to use &foo to reference structs, enums, typedefs, etc. in the Sphinx C domain. Thus do not prefix the links with "struct". Signed-off-by: Jani Nikula <jani.nikula@intel.com>
generated by cgit v1.2.3 (git 2.39.1) at 2024-12-16 20:57:03 +0100