Am 01.01.2017 um 15:05 schrieb Jonathan Cameron <[email protected]>:
> 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 [email protected]
More majordomo info at http://vger.kernel.org/majordomo-info.html
