1. 05 8月, 2016 1 次提交
  2. 04 8月, 2016 2 次提交
  3. 23 7月, 2016 1 次提交
    • M
      doc-rst: kernel-doc: fix handling of address_space tags · a88b1672
      Mauro Carvalho Chehab 提交于
      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: NMauro Carvalho Chehab <mchehab@s-opensource.com>
      Signed-off-by: NJonathan Corbet <corbet@lwn.net>
      a88b1672
  4. 21 7月, 2016 3 次提交
  5. 20 7月, 2016 1 次提交
    • D
      doc/sphinx: Enable keep_warnings · 47d6d752
      Daniel Vetter 提交于
      Unfortunately warnings generated after parsing in sphinx can end up
      with entirely bogus files and line numbers as sources. Strangely for
      outright errors this is not a problem. Trying to convert warnings to
      errors also doesn't fix it.
      
      The only way to get useful output out of sphinx to be able to root
      cause the error seems to be enabling keep_warnings, which inserts
      a System Message into the actual output. Not pretty at all, but I
      don't really want to fix up core rst/sphinx code, and this gets the job
      done meanwhile.
      
      Cc: Markus Heiser <markus.heiser@darmarit.de>
      Cc: Jonathan Corbet <corbet@lwn.net>
      Cc: linux-doc@vger.kernel.org
      Signed-off-by: NDaniel Vetter <daniel.vetter@intel.com>
      Signed-off-by: NJonathan Corbet <corbet@lwn.net>
      47d6d752
  6. 18 7月, 2016 3 次提交
  7. 10 7月, 2016 1 次提交
  8. 06 7月, 2016 1 次提交
  9. 02 7月, 2016 3 次提交
  10. 01 7月, 2016 3 次提交
  11. 24 6月, 2016 1 次提交
  12. 23 6月, 2016 6 次提交
  13. 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
  14. 04 6月, 2016 2 次提交
    • 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