• Daniel Vetter's avatar
    scripts/kernel-doc: Add option to inject line numbers · 0b0f5f29
    Daniel Vetter authored
    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: default avatarDaniel Vetter <daniel.vetter@ffwll.ch>
    Signed-off-by: default avatarJani Nikula <jani.nikula@intel.com>
    0b0f5f29
kernel-doc 86.5 KB