1. 10 Jun, 2016 3 commits
  2. 09 Jun, 2016 3 commits
    • Jonathan Corbet's avatar
      docs: kernel-doc: Add "example" and "note" to the magic section types · 8569de68
      Jonathan Corbet authored
      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: default avatarJonathan Corbet <corbet@lwn.net>
      8569de68
    • Kees Cook's avatar
      docs: self-protection: rename "leak" to "exposure" · c9de4a82
      Kees Cook authored
      The meaning of "leak" can be both "untracked resource allocation" and
      "memory content disclosure". This document's use was entirely of the
      latter meaning, so avoid the confusion by using the Common Weakness
      Enumeration name for this: Information Exposure (CWE-200). Additionally
      adds a section on structure randomization.
      Signed-off-by: default avatarKees Cook <keescook@chromium.org>
      Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      c9de4a82
    • Jonathan Corbet's avatar
      Merge branch 'sphinx-for-docs-next' into doc/4.8 · 6d5244c7
      Jonathan Corbet authored
      Jani Nikula says:
      
      Jon, this is v2 of [1] and [2], with a considerable amount of polish and
      fixes added. We started dogfooding this within drm-intel, and Daniel has
      reviewed the lot and contributed a number of fixes, most notably
      accurate file and line number references from Sphinx build
      errors/warnings to the kernel-doc comments in source code.
      
      We believe this is now in good shape for merging for v4.8. It's all in
      my sphinx-for-docs-next branch that you've already looked at; pull
      details below.
      
      When this lands in docs-next and we can backmerge to drm, we'll plunge
      ahead and convert gpu.tmpl to rst, and have that ready for v4.8. We
      think it's best to contribute that via the drm tree, as it'll involve
      splitting up the documentation and likely numerous updates to kernel-doc
      comments.
      
      I plan to update Documentation/kernel-doc-nano-HOWTO.txt for Sphinx and
      rst, obviously converting it to rst while at it.
      6d5244c7
  3. 04 Jun, 2016 2 commits
    • Daniel Vetter's avatar
      doc/sphinx: Track line-number of starting blocks · d90368f2
      Daniel Vetter authored
      Design is pretty simple: kernel-doc inserts breadcrumbs with line
      numbers, and sphinx picks them up. At first I went with a sphinx
      comment, but inserting those at random places seriously upsets the
      parser, and must be filtered. Hence why this version now uses "#define
      LINEO " since one of these ever escape into output it's pretty clear
      there is a bug.
      
      It seems to work well, and at least the 2-3 errors where sphinx
      complained about something that was not correct in kernel-doc text the
      line numbers matched up perfectly.
      
      v2: Instead of noodling around in the parser state machine, create
      a ViewList and parse it ourselves. This seems to be the recommended
      way, per Jani's suggestion.
      
      v3:
      - Split out ViewList pach. Splitting the kernel-doc changes from the
        sphinx ones isn't possible, since emitting the LINENO lines wreaks
        havoc with the rst formatting. We must filter them.
      
      - Improve the regex per Jani's suggestions, and compile it just once
        for speed.
      
      - Now that LINENO lines are eaten, also add them to function parameter
        descriptions. Much less content and offset than for in-line struct
        member descriptions, but still nice to know which exact continuation
        line upsets sphinx.
      
      - Simplify/clarify the line +/-1 business a bit.
      
      v4: Split out the scripts/kernel-doc changes and make line-numbers
      opt-in, as suggested 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>
      d90368f2
    • 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
  4. 03 Jun, 2016 8 commits
  5. 01 Jun, 2016 2 commits
  6. 30 May, 2016 22 commits