@@ -24,7 +24,8 @@
// // <mandatory short one-line description>
// // <optional blanck line>
// // @<1st paramater'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>
@@ -83,6 +84,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:
@@ -139,7 +152,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()
@@ -224,6 +237,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:
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> --- Documentation/sphinx/cdoc.py | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-)