From 7d4ab7f16d17313ffb45fb3e2fba20fd29a4f690 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Sat, 26 Nov 2022 12:50:40 +0100 Subject: [PATCH 1/2] [doc] kernel_doc: improve :internal: documentation Signed-off-by: Markus Heiser --- docs/linuxdoc-howto/all-in-a-tumble.c | 14 ----- docs/linuxdoc-howto/all-in-a-tumble.rst | 1 + docs/linuxdoc-howto/kernel-doc-tests.rst | 74 ++++++++++++++---------- docs/linuxdoc-howto/test_internals.c | 53 +++++++++++++++++ docs/linuxdoc-howto/test_internals.h | 9 +++ 5 files changed, 106 insertions(+), 45 deletions(-) create mode 100644 docs/linuxdoc-howto/test_internals.c create mode 100644 docs/linuxdoc-howto/test_internals.h diff --git a/docs/linuxdoc-howto/all-in-a-tumble.c b/docs/linuxdoc-howto/all-in-a-tumble.c index 4ffce65..700473d 100644 --- a/docs/linuxdoc-howto/all-in-a-tumble.c +++ b/docs/linuxdoc-howto/all-in-a-tumble.c @@ -51,20 +51,6 @@ int user_sum(int a, int b) } /* parse-SNAP: */ -/* parse-SNIP: internal_function */ -/** - * internal_function - the answer - * - * Context: !sanity() - * - * Return: - * The answer to the ultimate question of life, the universe and everything. - */ -int internal_function() -{ - return 42; -} -/* parse-SNAP: */ /* parse-SNIP: test_SYSCALL */ /** diff --git a/docs/linuxdoc-howto/all-in-a-tumble.rst b/docs/linuxdoc-howto/all-in-a-tumble.rst index 4a9f694..f16af8d 100644 --- a/docs/linuxdoc-howto/all-in-a-tumble.rst +++ b/docs/linuxdoc-howto/all-in-a-tumble.rst @@ -46,3 +46,4 @@ all-in-a-tumble.c .. kernel-doc:: ./all-in-a-tumble.c :module: example + :known-attrs: API_EXPORTED diff --git a/docs/linuxdoc-howto/kernel-doc-tests.rst b/docs/linuxdoc-howto/kernel-doc-tests.rst index 6837b32..16598c3 100644 --- a/docs/linuxdoc-howto/kernel-doc-tests.rst +++ b/docs/linuxdoc-howto/kernel-doc-tests.rst @@ -247,36 +247,44 @@ option ``:internal:`` --------------------- Include documentation of all documented definitions, **not** exported. This -test gathers exports from :ref:`all-in-a-tumble.h-src` and -:ref:`all-in-a-tumble.c-src` and parses comments from -:ref:`all-in-a-tumble.c-src`, from where only the *not exported* definitions are -used in the reST output. +test gathers exports from :origin:`test_internals.h +` and :origin:`test_internals.c +` and parses comments from +:origin:`test_internals.c `, from where +only the *not exported* definitions are used in the reST output. + +.. attention:: -The both examples below also demonstrate that it is not supported to mix the -export methods (``:exp-method:``) ``[macro|attribute]`` in one source -``all-in-a-tumble.[hc]``. Only one methode can be used by the ``:internal:`` -option to identfy if a symbol is exported. + The both examples below also demonstrate that it is not good to mix the + export methods (``:exp-method: [macro|attribute]``) in one source + ``test_internals.[hc]``. Only one methode can be used by the ``:internal:`` + option to identfy a symbol to be exported. .. tabs:: .. group-tab:: exp-method is ``macro`` - From :ref:`all-in-a-tumble.h-src`: + From :``test_internals.h``: - .. kernel-doc:: ./all-in-a-tumble.h - :snippets: EXPORT_SYMBOL + .. kernel-doc:: ./test_internals.h + :snippets: EXP_SYMB - From :ref:`all-in-a-tumble.c-src`: + From ``test_internals.c``: - .. kernel-doc:: ./all-in-a-tumble.c - :snippets: user_function + .. kernel-doc:: ./test_internals.c + :snippets: EXP_SYMB .. group-tab:: exp-method is ``attribute`` - From :ref:`all-in-a-tumble.c-src`: + From ``test_internals.c``: + + .. kernel-doc:: ./test_internals.c + :snippets: API_EXP + + From ``test_internals.h``: - .. kernel-doc:: ./all-in-a-tumble.c - :snippets: user_sum-c + .. kernel-doc:: ./test_internals.h + :snippets: API_EXP .. tabs:: @@ -284,35 +292,39 @@ option to identfy if a symbol is exported. .. code-block:: rst - .. kernel-doc:: ./all-in-a-tumble.c - :internal: ./all-in-a-tumble.h - :module: tests.internal + .. kernel-doc:: ./test_internals.c + :internal: ./test_internals.h + :module: test_internals_A + :exp-method: macro + :exp-ids: EXP_SYMB .. admonition:: internal symbols (when exp-method is ``macro``) :class: rst-example - .. kernel-doc:: ./all-in-a-tumble.c - :internal: ./all-in-a-tumble.h - :module: tests.internal_A + .. kernel-doc:: ./test_internals.c + :internal: ./test_internals.h + :module: test_internals_A + :exp-method: macro + :exp-ids: EXP_SYMB .. group-tab:: exp-method is ``attribute`` .. code-block:: rst - .. kernel-doc:: ./all-in-a-tumble.c - :internal: ./all-in-a-tumble.h - :module: tests.internal_B + .. kernel-doc:: ./test_internals.c + :internal: ./test_internals.h + :module: test_internals_B :exp-method: attribute - :exp-ids: API_EXPORTED + :exp-ids: API_EXP .. admonition:: internal symbols (when exp-method is ``attribute``) :class: rst-example - .. kernel-doc:: ./all-in-a-tumble.c - :internal: ./all-in-a-tumble.h - :module: tests.internal_B + .. kernel-doc:: ./test_internals.c + :internal: ./test_internals.h + :module: test_internals_B :exp-method: attribute - :exp-ids: API_EXPORTED + :exp-ids: API_EXP Missing exports diff --git a/docs/linuxdoc-howto/test_internals.c b/docs/linuxdoc-howto/test_internals.c new file mode 100644 index 0000000..0efb879 --- /dev/null +++ b/docs/linuxdoc-howto/test_internals.c @@ -0,0 +1,53 @@ +/* parse-SNIP: EXP_SYMB */ +/** + * foo() - function that can only be called in user context + * @a: some argument + * @...: ellipsis operator + * + * This function makes no sense, it's only a kernel-doc demonstration. + * + * Example: + * x = foo(42); + * + * Return: + * Returns first argument + */ +int foo(int a, ...) +{ + return a; +} +/* parse-SNAP: */ + +/* parse-SNIP: API_EXP */ +/** + * bar() - function that can only be called in user context + * @a: some argument + * @...: ellipsis operator + * + * This function makes no sense, it's only a kernel-doc demonstration. + * + * Example: + * x = bar(42); + * + * Return: + * Returns first argument + */ +API_EXP int bar(int a, ...) +{ + return a; +} + +/* parse-SNIP: internal_function */ +/** + * internal_function() - the answer + * + * Context: !sanity() + * + * Return: + * The answer to the ultimate question of life, the universe and everything. + */ +int internal_function() +{ + return 42; +} +/* parse-SNAP: */ diff --git a/docs/linuxdoc-howto/test_internals.h b/docs/linuxdoc-howto/test_internals.h new file mode 100644 index 0000000..7284458 --- /dev/null +++ b/docs/linuxdoc-howto/test_internals.h @@ -0,0 +1,9 @@ +/* parse-SNIP: EXP_SYMB */ +EXP_SYMB(foo) + +int foo(int a, ...) +/* parse-SNAP: */ + +/* parse-SNIP: API_EXP */ +int bar(int a, int b); +/* parse-SNAP: */ From 0f2eb7907252aa8556a72ced3ae8a3159a3f5eda Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Sun, 27 Nov 2022 09:38:08 +0100 Subject: [PATCH 2/2] WIP Signed-off-by: Markus Heiser --- Makefile | 4 ++-- linuxdoc/kernel_doc.py | 6 +++--- linuxdoc/rstKernelDoc.py | 4 ++++ 3 files changed, 9 insertions(+), 5 deletions(-) diff --git a/Makefile b/Makefile index b2cbadc..e306e40 100644 --- a/Makefile +++ b/Makefile @@ -42,11 +42,11 @@ PHONY += uninstall uninstall: pyenvuninstall PHONY += docs -docs: docs-man $(API_DOC) +docs: $(call cmd,sphinx,html,docs,docs) PHONY += docs-live -docs-live: pyenvinstall docs-man +docs-live: pyenvinstall $(call cmd,sphinx_autobuild,html,$(DOCS_FOLDER),$(DOCS_FOLDER)) PHONY += docs-man diff --git a/linuxdoc/kernel_doc.py b/linuxdoc/kernel_doc.py index b0cd39c..0c8e3d0 100755 --- a/linuxdoc/kernel_doc.py +++ b/linuxdoc/kernel_doc.py @@ -360,9 +360,9 @@ def write(self, *args, **kwargs): , log_out = sys.__stderr__ , ) -VERBOSE = False -DEBUG = False -INSPECT = False +VERBOSE = True +DEBUG = True +INSPECT = True class SimpleLog(object): diff --git a/linuxdoc/rstKernelDoc.py b/linuxdoc/rstKernelDoc.py index d1f500e..67649c5 100755 --- a/linuxdoc/rstKernelDoc.py +++ b/linuxdoc/rstKernelDoc.py @@ -363,6 +363,10 @@ def run(self): raise FaultyOption('docutils: file insertion disabled') opts = self.getParserOptions() # FIXME: think about again; these members has been added for convenience + #if opts['rel_fname'].startswith('./test_internal') and len(opts.get('exp_ids', [])) ==1: + # import pdb + # pdb.set_trace() + self.parser = self.parseSource(opts) # pylint: disable=attribute-defined-outside-init self.nodes.extend(self.getNodes())