1. 02 7月, 2016 1 次提交
  2. 01 7月, 2016 3 次提交
  3. 24 6月, 2016 1 次提交
  4. 23 6月, 2016 6 次提交
  5. 10 6月, 2016 12 次提交
    • J
      Documentation/sphinx: add support for specifying extra export files · 03d35d9e
      Jani Nikula 提交于
      Let the user specify file patterns where to look for the EXPORT_SYMBOLs
      in addition to the file with kernel-doc comments. This is directly based
      on the -export-file FILE option added to kernel-doc in "kernel-doc: add
      support for specifying extra files for EXPORT_SYMBOLs", but we extend
      that with globbing patterns in the Sphinx extension.
      
      The file patterns are added as options to the :export: and :internal:
      arguments of the kernel-doc directive. For example, to extract the
      documentation of exported functions from include/net/mac80211.h:
      
      .. kernel-doc:: include/net/mac80211.h
         :export: net/mac80211/*.c
      
      Without the file pattern, no exported functions would be found, as the
      EXPORT_SYMBOLs are placed in the various source files under
      net/mac80211.
      
      The matched files are also added as dependencies on the document in
      Sphinx, as they may affect the output. This is one of the reasons to do
      the globbing in the Sphinx extension instead of in scripts/kernel-doc.
      
      The file pattern remains optional, and is not needed if the kernel-doc
      comments and EXPORT_SYMBOLs are placed in the source file passed in as
      the main argument to the kernel-doc directive. This is the most common
      case across the kernel source tree.
      Signed-off-by: NJani Nikula <jani.nikula@intel.com>
      03d35d9e
    • J
      Documentation/sphinx: use a more sensible string split in kernel-doc extension · 057de5c4
      Jani Nikula 提交于
      Using the default str.split doesn't return empty strings like the
      current version does.
      Signed-off-by: NJani Nikula <jani.nikula@intel.com>
      057de5c4
    • J
      Documentation/sphinx: remove unnecessary temporary variable · 06173fe3
      Jani Nikula 提交于
      Leftover cruft. No functional changes.
      Signed-off-by: NJani Nikula <jani.nikula@intel.com>
      06173fe3
    • J
      kernel-doc: unify all EXPORT_SYMBOL scanning to one place · c9b2cfb3
      Jani Nikula 提交于
      Scan all input files for EXPORT_SYMBOLs along with the explicitly
      specified export files before actually parsing anything.
      Signed-off-by: NJani Nikula <jani.nikula@intel.com>
      c9b2cfb3
    • J
      kernel-doc: add support for specifying extra files for EXPORT_SYMBOLs · 88c2b57d
      Jani Nikula 提交于
      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: NJani Nikula <jani.nikula@intel.com>
      88c2b57d
    • J
      kernel-doc: abstract filename mapping · 1ad560e4
      Jani Nikula 提交于
      Reduce duplication in follow-up work. No functional changes.
      Signed-off-by: NJani Nikula <jani.nikula@intel.com>
      1ad560e4
    • J
      da9726ec
    • J
      kernel-doc: do not warn about duplicate default section names · 95b6be9d
      Jani Nikula 提交于
      Since
      
      commit 32217761
      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: NJani Nikula <jani.nikula@intel.com>
      95b6be9d
    • J
      kernel-doc: remove old debug cruft from dump_section() · 5668604a
      Jani Nikula 提交于
      No functional changes.
      Signed-off-by: NJani Nikula <jani.nikula@intel.com>
      5668604a
    • J
      docs: kernel-doc: Add "example" and "note" to the magic section types · 8569de68
      Jonathan Corbet 提交于
      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: NJonathan Corbet <corbet@lwn.net>
      8569de68
    • K
      docs: self-protection: rename "leak" to "exposure" · c9de4a82
      Kees Cook 提交于
      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: NKees Cook <keescook@chromium.org>
      Signed-off-by: NJonathan Corbet <corbet@lwn.net>
      c9de4a82
    • J
      Merge branch 'sphinx-for-docs-next' into doc/4.8 · 6d5244c7
      Jonathan Corbet 提交于
      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
  6. 04 6月, 2016 7 次提交
    • D
      doc/sphinx: Track line-number of starting blocks · d90368f2
      Daniel Vetter 提交于
      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: NDaniel Vetter <daniel.vetter@ffwll.ch>
      Signed-off-by: NJani Nikula <jani.nikula@intel.com>
      d90368f2
    • D
      scripts/kernel-doc: Add option to inject line numbers · 0b0f5f29
      Daniel Vetter 提交于
      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: NDaniel Vetter <daniel.vetter@ffwll.ch>
      Signed-off-by: NJani Nikula <jani.nikula@intel.com>
      0b0f5f29
    • N
    • A
      Documentation/zh_CN: update Chinese version CodingStyle · 49e48419
      Andy Deng 提交于
      Chinese version CodingStyle is a little outdate, it should be updated.
      
      This patch sync with the latest CodingStyle of all changes,
      new chapters (chapter 19 and chapter 20) have been translated.
      Signed-off-by: NAndy Deng <theandy.deng@gmail.com>
      Signed-off-by: NJonathan Corbet <corbet@lwn.net>
      49e48419
    • B
      doc: clarify that trace_events= takes a comma-separated list · d81749ea
      Brian Norris 提交于
      It took me browsing through the source code to determine that I was,
      indeed, using the wrong delimiter in my command lines. So I might as
      well document it for the next person.
      Signed-off-by: NBrian Norris <computersforpeace@gmail.com>
      Acked-by: NSteven Rostedt <rostedt@goodmis.org>
      Signed-off-by: NJonathan Corbet <corbet@lwn.net>
      d81749ea
    • M
      mpssd: fix buffer overflow warning · 3610a2ad
      Mike Danese 提交于
      The compilation emits a warning in function ‘snprintf’,
          inlined from ‘set_cmdline’ at
          ../Documentation/mic/mpssd/mpssd.c:1541:9:
      /usr/include/x86_64-linux-gnu/bits/stdio2.h:64:10:
          warning: call to __builtin___snprintf_chk will always overflow
          destination buffer
      
      This was introduced in commit f4a66c20 ("misc: mic: Update MIC host
      daemon with COSM changes") and is fixed by reverting the changes to the
      size argument of these snprintf statements.
      
      Cc: Ashutosh Dixit <ashutosh.dixit@intel.com>
      Signed-off-by: NMike Danese <mikedanese@google.com>
      Signed-off-by: NJonathan Corbet <corbet@lwn.net>
      3610a2ad
    • J
      Documentation: Fix some grammar mistakes in sync_file.txt · fac8434d
      Javier Martinez Canillas 提交于
      There are two sentences in the Sync File documentation where the
      english is a little off. This patch is an attempt to fix these.
      Signed-off-by: NJavier Martinez Canillas <javier@osg.samsung.com>
      Reviewed-by: NGustavo Padovan <gustavo.padovan@collabora.co.uk>
      Signed-off-by: NJonathan Corbet <corbet@lwn.net>
      fac8434d
  7. 03 6月, 2016 3 次提交
  8. 01 6月, 2016 2 次提交
  9. 30 5月, 2016 5 次提交
    • J
      kernel-doc: reset contents and section harder · 2f4ad40a
      Jani Nikula 提交于
      If the documentation comment does not have params or sections, the
      section heading may leak from the previous documentation comment.
      Signed-off-by: NJani Nikula <jani.nikula@intel.com>
      2f4ad40a
    • J
      kernel-doc: concatenate contents of colliding sections · 32217761
      Jani Nikula 提交于
      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: NJani Nikula <jani.nikula@intel.com>
      32217761
    • J
      kernel-doc: limit the "section header:" detection to a select few · f624adef
      Jani Nikula 提交于
      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: NJani Nikula <jani.nikula@intel.com>
      f624adef
    • J
      kernel-doc/rst: remove fixme comment · cddfe325
      Jani Nikula 提交于
      Yes, for our purposes the type should contain typedef.
      Signed-off-by: NJani Nikula <jani.nikula@intel.com>
      cddfe325
    • J
      kernel-doc/rst: use *undescribed* instead of _undescribed_ · d4b08e0c
      Jani Nikula 提交于
      The latter isn't special to rst.
      Signed-off-by: NJani Nikula <jani.nikula@intel.com>
      d4b08e0c