summaryrefslogtreecommitdiffstats
path: root/scripts/kernel-doc
Commit message (Collapse)AuthorAgeFilesLines
* 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-171-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>
* kernel-doc/rst: reference functions according to C domain specJani Nikula2016-05-301-1/+1
| | | | | | | The Sphinx C domain spec says function references should include the parens (). Signed-off-by: Jani Nikula <jani.nikula@intel.com>
* kernel-doc/rst: do not output DOC: section titles for requested onesJani Nikula2016-05-301-1/+3
| | | | | | | | | If the user requests a specific DOC: section by name, do not output its section title. In these cases, the surrounding context already has a heading, and the DOC: section title is only used as an identifier and a heading for clarity in the source file. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
* kernel-doc: add names for output selectionJani Nikula2016-05-301-17/+30
| | | | | | | | | | Make the output selection a bit more readable by adding constants for the various types of output selection. While at it, actually call the variable for choosing what to output $output_selection. No functional changes. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
* kernel-doc: add names for states and substatesJani Nikula2016-05-301-43/+48
| | | | | | | | | | Make the state machine a bit more readable by adding constants for parser states and inline member documentation parser substates. While at it, rename the "split" documentation to "inline" documentation. No functional changes. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
* kernel-doc: support printing exported and non-exported symbolsJani Nikula2016-05-301-2/+27
| | | | | | | | | | | | | | | | | | | | | | | | Currently we use docproc to figure out which symbols are exported, and then docproc calls kernel-doc on specific functions, to get documentation on exported functions. According to git blame and docproc comments, this is due to historical reasons, as functions and their corresponding EXPORT_SYMBOL* may have been in different files. However for more than ten years the recommendation in CodingStyle has been to place the EXPORT_SYMBOL* immediately after the closing function brace line. Additionally, the kernel-doc comments for functions are generally placed above the function definition in the .c files (i.e. where the EXPORT_SYMBOL* is) rather than above the declaration in the .h files. There are some exceptions to this, but AFAICT none of these are included in DocBook documentation using the "!E" docproc directive. Therefore, assuming the EXPORT_SYMBOL* and kernel-doc are with the function definition, kernel-doc can extract the exported vs. not information by making two passes on the input file. Add support for that via the new -export and -internal parameters. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
* kernel-doc/rst: fix use of uninitialized valueJani Nikula2016-05-301-1/+2
| | | | | | | | | | I'm not quite sure why the errors below are happening, but this fixes them. Use of uninitialized value in string ne at ./scripts/kernel-doc line 1819, <IN> line 6494. Use of uninitialized value $_[0] in join or string at ./scripts/kernel-doc line 1759, <IN> line 6494. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
* kernel-doc: use rst C domain directives and references for typesJani Nikula2016-05-141-10/+9
| | | | | | | | | | | First, the headings for structs, enums and typedefs will be similar to functions. Second, this provides a kind of namespace for cross references. Third, and most importantly, the return and parameter types from .. c:function:: definitions will automagically become cross references to the documented types. Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* kernel-doc: produce RestructuredText outputJonathan Corbet2016-05-141-0/+233
| | | | | | | | | | | | | | | | If given the -rst flag, output will now be in RestructuredText. Various glitches to be worked out yet. In the end I decided not to use RST section headings within the kerneldoc comments. gpu.tmpl already has headings five levels deep; adding more is not going to bring clarity. This is really just Jani Nikula's asciidoc change with the serial numbers filed off. It's a hack job that doubtless needs a lot of cleaning up. Signed-off-by: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* kernel-doc: rewrite usage description, remove duplicated commentsJani Nikula2016-05-141-46/+37
| | | | | | | | | Instead of having the kernel-doc usage in both comments and in output to the user, merge them all to one here document. While at it, imrove the text and make it pretty. Give shoemaker's children some shoes. Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* Merge tag 'docs-4.5' of git://git.lwn.net/linuxLinus Torvalds2016-01-171-1/+4
|\ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Pull documentation updates from Jon Corbet: "A relatively boring cycle in the docs tree. There's a few kernel-doc fixes and various document tweaks. One patch reaches out of the documentation subtree to fix a comment in init/do_mounts_rd.c. There didn't seem to be anybody more appropriate to take that one, so I accepted it" * tag 'docs-4.5' of git://git.lwn.net/linux: (29 commits) thermal: add description for integral_cutoff unit Documentation: update libhugetlbfs site url Documentation: Explain pci=conf1,conf2 more verbosely DMA-API: fix confusing sentence in Documentation/DMA-API.txt Documentation: translations: update linux cross reference link Documentation: fix typo in CodingStyle init, Documentation: Remove ramdisk_blocksize mentions Documentation-getdelays: Apply a recommendation from "checkpatch.pl" in main() Documentation: HOWTO: update versions from 3.x to 4.x Documentation: remove outdated references from translations Doc: treewide: Fix grammar "a" to "an" Documentation: cpu-hotplug: Fix sysfs mount instructions can-doc: Add hint about getting timestamps Fix CFQ I/O scheduler parameter name in documentation Documentation: arm: remove dead links from Marvell Berlin docs Documentation: HOWTO: update code cross reference link Doc: Docbook/iio: Fix typo in iio.tmpl DocBook: make index.html generation less verbose by default DocBook: Cleanup: remove an unused $(call) line DocBook: Add a help message for DOCBOOKS env var ...
| * kernel-doc: Fix parsing of DECLARE_BITMAP in structConchúr Navid2015-11-201-0/+2
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Some documented structures in the kernel use DECLARE_BITMAP to create arrays of unsigned longs to store information using the bitmap functions. These have to be replaced with a parsable version for kernel-doc. For example a simple input like /** * struct something - some test * @members: active members */ struct something { DECLARE_BITMAP(members, MAX_MEMBERS); }; resulted in parsing warnings like warning: No description found for parameter 'MAX_MEMBERS)' warning: Excess struct/union/enum/typedef member 'members' description in 'something' Signed-off-by: Conchúr Navid <conchur@web.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
| * kernel-doc: Strip #ifdef/#endif in enumsConchúr Navid2015-11-201-1/+2
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Some enumerations in the kernel headers use #ifdef to reduce their size based on the the configuration. These lines have to be stripped to avoid parsing problems. For example a simple input like /** * enum flags - test flags * @flag1: first flag * @flag2: second flag */ enum flags { flag1 = BIT(0), #ifdef SECOND_FLAG flag2 = BIT(1), #endif }; resulted in parsing warnings like warning: Enum value '#ifdef SECOND_FLAG;flag2 = BIT(1)' not described in enum 'flags' warning: Enum value '#endif;' not described in enum 'flags' Signed-off-by: Conchúr Navid <conchur@web.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
| * kernel-doc: Fix stripping of #define in enumsConchúr Navid2015-11-201-1/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The regex to strip single line #define's in enumerations depends on the fact that the defines are still stored on separate lines. But the surrounding code already removed newlines and replaced them with semicolons. For example a simple input like /** * enum flags - test flags * @flag1: first flag * @flag2: second flag * @flag3: third flag * @flag4: fourth flag */ enum flags { flag1 = BIT(0), flag2 = BIT(1), #define flags_small (flag1 | flag2) flag3 = BIT(2), flag4 = BIT(3), #define flags_big (flag2 | flag3) }; resulted in parsing warnings like warning: Enum value '#define flags_small (flag1 | flag2);flag3 = BIT(2)' not described in enum 'flags' warning: Enum value '#define flags_big (flag2 | flag3);' not described in enum 'flags' Signed-off-by: Conchúr Navid <conchur@web.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* | kernel-doc: Make it compatible with Perl versions below 5.12 againMauro Carvalho Chehab2015-11-171-1/+1
|/ | | | | | | | | | | | | | Changeset 4d73270192ec('scripts/kernel-doc: Replacing highlights hash by an array') broke compatibility of the kernel-doc script with older versions of perl by using "keys ARRAY" syntax with is available only on Perl 5.12 or newer, according with: http://perldoc.perl.org/functions/keys.html Restore backward compatibility by replacing "foreach my $k (keys ARRAY)" by a C-like variant: "for (my $k = 0; $k < !ARRAY; $k++)" Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* Merge tag 'docs-for-linus' of git://git.lwn.net/linuxLinus Torvalds2015-11-051-51/+68
|\ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Pull documentation update from Jon Corbet: "There is a nice new document from Neil on how pathname lookups work and some new CAN driver documentation. Beyond that, we have kernel-doc fixes, a bit more work to support reproducible builds, and the usual collection of small fixes" * tag 'docs-for-linus' of git://git.lwn.net/linux: (34 commits) Documentation: add new description of path-name lookup. Documentation/vm/slub.txt: document slabinfo-gnuplot.sh Doc: ABI/stable: Fix typo in ABI/stable doc: Clarify that nmi_watchdog param is for hardlockups Typo correction for description in gpio document. DocBook: Fix kernel-doc to be case-insensitive for private: kernel-docs.txt: update kernelnewbies reference Doc:kvm: Fix typo in Doc/virtual/kvm Documentation/Changes: Add bc in "Current Minimal Requirements" section Documentation/email-clients.txt: remove trailing whitespace DocBook: Use a fixed encoding for output MAINTAINERS: The docs tree has moved Docs/kernel-parameters: Add earlycon devicetree usage SubmittingPatches: make Subject examples match the de facto standard Documentation: gpio: mention that <function>-gpio has been deprecated Documentation: cgroups: just fix a few typos Documentation: Update kselftest.txt Documentation: DMA API: Be more explicit that nents is always the same Documentation: Update the default value of crashkernel low zram: update documentation ...
generated by cgit v1.2.3 (git 2.25.1) at 2024-12-27 14:05:35 +0000