On 05/19/18 06:05, Luc Van Oostenryck wrote:
> Add a tool which parse comment from source files and
> extract kerneldoc-like documentation from them.
>
> Note: this is rather quite crude, support only generic 'blocs'
> and doc for functions; it has no support for anything else.
>
> Signed-off-by: Luc Van Oostenryck <luc.vanoostenryck@xxxxxxxxx>
> ---
> .gitignore | 1 +
> Documentation/sphinx/cdoc.py | 200 +++++++++++++++++++++++++++++++++++
> 2 files changed, 201 insertions(+)
> create mode 100755 Documentation/sphinx/cdoc.py
>
> diff --git a/Documentation/sphinx/cdoc.py b/Documentation/sphinx/cdoc.py
> new file mode 100755
> index 000000000..4eae75e89
> --- /dev/null
> +++ b/Documentation/sphinx/cdoc.py
> @@ -0,0 +1,200 @@
> +#!/usr/bin/env python
> +# SPDX_License-Identifier: MIT
> +#
> +# Copyright (C) 2018 Luc Van Oostenryck <luc.vanoostenryck@xxxxxxxxx>
> +#
> +
> +"""
> +///
> +// Sparse source files may contain documentation inside block-comments
> +// specifically formatted::
> +//
> +// ///
> +// // Here is some doc
> +// // and here is some more.
> +//
> +// More precisely, a doc-block begins with a line containting only ``///``
containing
> +// and continues with lines beginning by ``//`` followed by either a space,
> +// a tab or nothing, the first space after ``//`` is ignored.
> +//
> +// For functions, some additional syntax must be respected inside the
> +// block-comment::
> +//
> +// ///
> +// // <mandatory short one-line description>
> +// // <optional blanck line>
blank
> +// // @<1st paramater's name>: <description>
parameter's
> +// // @<2nd parameter's name>: ...
> +// // @return: <description> (absent for void functions)
> +// // <optional blank line>
> +// // <optional long multi-line description>
> +// int somefunction(void *ptr, int count);
> +//
> +// Inside the description fields, parameter's names can be referenced
> +// by using ``@<parameter name>``. A function doc-block must directly
must directly precede
> +// the function it documents. This function can span multiple lines and
> +// can either be a function prototype (ending with ``;``) or a
> +// function definition.
> +//
> +// Some future versions will also allow to document structures, unions,
> +// enums, typedefs and variables.
> +//
--
~Randy
--
To unsubscribe from this list: send the line "unsubscribe linux-sparse" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
