Am 01.01.2017 um 15:05 schrieb Jonathan Cameron <jic23@xxxxxxxxxx>: > Hi All, > > I have very little idea how the internals of the kernel-doc processing > code work, but was wondering if it would be possible to suppress warnings > of the type: > > ./include/linux/iio/buffer.h:142: warning: Excess struct/union/enum/typedef member 'ref' description in 'iio_buffer' > > when the member is there but has been marked private. It seems we have different ./include/linux/iio/buffer.h, I can't reproduce this or similar message. So I guess what you mean ... In scripts/kernel_doc there is some handling of privates in function 'dump_struct' ... # ignore members marked private: $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi; $members =~ s/\/\*\s*private:.*//gosi; Can you give a detailed example, to see what goes wrong? > I don't really want to end up deliberately having different formatting > for documentation of internal structure elements and public API ones. > > Obviously I can just ignore the warnings, but they do swamp any real issues > once you start dealing with large structures. > > Any thoughts? Yes, even if they are OT ... IMO we should no longer investigate in the kernel_doc perl script, which is at it ends. Instead we should merge the python version from my linuxdoc project (BTW: with, we get man-pages from and lint of kernel-doc comments). To see how this python version works, run: pip install [--user] git+http://github.com/return42/linuxdoc.git And apply the patch attached below. For a detailed description of this patch read: https://return42.github.io/linuxdoc/linux.html -- Markus -- ---- diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx index 707c653..b9eea4c 100644 --- a/Documentation/Makefile.sphinx +++ b/Documentation/Makefile.sphinx @@ -37,8 +37,7 @@ HAVE_PDFLATEX := $(shell if which $(PDFLATEX) >/dev/null 2>&1; then echo 1; else PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter KERNELDOC = $(srctree)/scripts/kernel-doc -KERNELDOC_CONF = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC) -ALLSPHINXOPTS = $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) +ALLSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) # the i18n builder cannot share the environment and doctrees with the others I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . @@ -93,9 +92,12 @@ xmldocs: # no-ops for the Sphinx toolchain sgmldocs: psdocs: -mandocs: installmandocs: +mandocs: + @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,kernel-doc-man,$(var),man,$(var))) + + cleandocs: $(Q)rm -rf $(BUILDDIR) $(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) -C Documentation/media clean diff --git a/Documentation/conf.py b/Documentation/conf.py index 1ac958c..b5903c6 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -34,7 +34,13 @@ from load_config import loadConfig # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain'] +extensions = [ + 'linuxdoc.rstKernelDoc', + 'linuxdoc.rstFlatTable', + 'linuxdoc.kernel_include', + 'linuxdoc.manKernelDoc', + 'linuxdoc.cdomain', + 'sphinx.ext.todo', ] # The name of the math extension changed on Sphinx 1.4 if major == 1 and minor > 3: @@ -133,7 +139,7 @@ pygments_style = 'sphinx' #keep_warnings = False # If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = False +todo_include_todos = True primary_domain = 'C' highlight_language = 'none' @@ -385,10 +391,7 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'thelinuxkernel', 'The Linux Kernel Documentation', - [author], 1) -] +man_pages = [] # If true, show URL addresses after external links. #man_show_urls = False @@ -505,8 +508,9 @@ pdf_documents = [ # kernel-doc extension configuration for running Sphinx directly (e.g. by Read # the Docs). In a normal build, these are supplied from the Makefile via command # line arguments. -kerneldoc_bin = '../scripts/kernel-doc' -kerneldoc_srctree = '..' +kernel_doc_verbose_warn = False +kernel_doc_raise_error = False +kernel_doc_mode = "reST" # ------------------------------------------------------------------------------ # Since loadConfig overwrites settings from the global namespace, it has to be diff --git a/Documentation/index.rst b/Documentation/index.rst index cb5d776..066104e 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -72,3 +72,5 @@ Indices and tables ================== * :ref:`genindex` + +.. todolist:: -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
