diff options
| author | Luc Van Oostenryck <luc.vanoostenryck@gmail.com> | 2018-05-16 14:55:33 +0200 |
|---|---|---|
| committer | Luc Van Oostenryck <luc.vanoostenryck@gmail.com> | 2018-05-21 03:06:27 +0200 |
| commit | b5b7da4222c11ab90c736bda471dfa46685ee320 (patch) | |
| tree | 7e525df9d359877f920990f67a844a41833ac4c5 /Documentation/sphinx | |
| parent | 1e76c0fb84430760d8a63f67b8cfe8f8bab4efbf (diff) | |
| download | sparse-dev-b5b7da4222c11ab90c736bda471dfa46685ee320.tar.gz | |
autodoc: support muti-line param & return descriptions
Short descriptions are good but sometimes you can't describe
thinsg well enough with a single line.
So, add support for multi-line descriptions.
The additional lines need to be indented with a tab to be
recognized as such.
Signed-off-by: Luc Van Oostenryck <luc.vanoostenryck@gmail.com>
Diffstat (limited to 'Documentation/sphinx')
| -rwxr-xr-x | Documentation/sphinx/cdoc.py | 20 |
1 files changed, 17 insertions, 3 deletions
diff --git a/Documentation/sphinx/cdoc.py b/Documentation/sphinx/cdoc.py index 75eb241a..2718c86a 100755 --- a/Documentation/sphinx/cdoc.py +++ b/Documentation/sphinx/cdoc.py @@ -24,7 +24,8 @@ // // <mandatory short one-line description> // // <optional blank line> // // @<1st parameter's name>: <description> -// // @<2nd parameter's name>: ... +// // @<2nd parameter's name>: <long description +// // <tab>which needs multiple lines> // // @return: <description> (absent for void functions) // // <optional blank line> // // <optional long multi-line description> @@ -80,6 +81,18 @@ class Lines: # type: () -> None self.back = True +def readline_multi(lines, line): + # type: (Lines, str) -> str + try: + while True: + (n, l) = next(lines) + if not l.startswith('//\t'): + raise StopIteration + line += '\n' + l[3:] + except: + lines.undo() + return line + def readline_delim(lines, delim): # type: (Lines, Tuple[str, str]) -> Tuple[int, str] try: @@ -136,7 +149,7 @@ def process_block(lines): sep = m.group(2) ## FIXME/ warn if sep != ': ' l = m.group(3) - ## FIXME: try multi-line ??? + l = readline_multi(lines, l) tags.append((n, tag, l)) else: lines.undo() @@ -221,6 +234,7 @@ def convert_to_rst(info): name = 'param ' + name l = decorate(l) l = '\t:%s: %s' % (name, l) + l = '\n\t\t'.join(l.split('\n')) lst.append((n, l)) lst.append((n+1, '')) if 'desc' in info: @@ -292,7 +306,7 @@ def setup(app): app.add_directive_to_domain('c', 'autodoc', CDocDirective) return { - 'version': '0.9', + 'version': '1.0', 'parallel_read_safe': True, } |