1. 24 Jun, 2016 1 commit
  2. 23 Jun, 2016 6 commits
  3. 10 Jun, 2016 9 commits
  4. 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
  5. 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
  6. 03 Jun, 2016 8 commits
  7. 01 Jun, 2016 2 commits
  8. 30 May, 2016 9 commits
    • Jani Nikula's avatar
      kernel-doc: reset contents and section harder · 2f4ad40a
      Jani Nikula authored
      If the documentation comment does not have params or sections, the
      section heading may leak from the previous documentation comment.
      Signed-off-by: default avatarJani Nikula <jani.nikula@intel.com>
      2f4ad40a
    • Jani Nikula's avatar
      kernel-doc: concatenate contents of colliding sections · 32217761
      Jani Nikula authored
      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: default avatarJani Nikula <jani.nikula@intel.com>
      32217761
    • Jani Nikula's avatar
      kernel-doc: limit the "section header:" detection to a select few · f624adef
      Jani Nikula authored
      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: default avatarJani Nikula <jani.nikula@intel.com>
      f624adef
    • Jani Nikula's avatar
      kernel-doc/rst: remove fixme comment · cddfe325
      Jani Nikula authored
      Yes, for our purposes the type should contain typedef.
      Signed-off-by: default avatarJani Nikula <jani.nikula@intel.com>
      cddfe325
    • Jani Nikula's avatar
      kernel-doc/rst: use *undescribed* instead of _undescribed_ · d4b08e0c
      Jani Nikula authored
      The latter isn't special to rst.
      Signed-off-by: default avatarJani Nikula <jani.nikula@intel.com>
      d4b08e0c
    • Jani Nikula's avatar
      kernel-doc: strip leading whitespace from continued param descs · b7886de4
      Jani Nikula authored
      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: default avatarJani Nikula <jani.nikula@intel.com>
      b7886de4
    • Jani Nikula's avatar
      kernel-doc: improve handling of whitespace on the first line param description · 0a726301
      Jani Nikula authored
      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: default avatarJani Nikula <jani.nikula@intel.com>
      0a726301
    • Jani Nikula's avatar
      kernel-doc/rst: change the output layout · ecbcfba1
      Jani Nikula authored
      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: default avatarJani Nikula <jani.nikula@intel.com>
      ecbcfba1
    • Jani Nikula's avatar
      kernel-doc: strip leading blank lines from inline doc comments · 6450c895
      Jani Nikula authored
      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: default avatarJani Nikula <jani.nikula@intel.com>
      6450c895