On Tue, 08 Jan 2019, Bruno Santos <brunomanuelsantos@xxxxxxxxxxxxxxxxxx> wrote:
This is one of a series of patches aimed at isolating each functionality
in its own module. At the moment everything is quite small and
manageable, but many features are nonetheless independent and can
achieve better decoupling.
In this case, the split will help in furthering compatibility options
while keeping away from the core parsing logic.
---
hawkmoth/hawkmoth.py | 59 ++++---------------------------------
hawkmoth/util/__init__.py | 0
hawkmoth/util/doccompat.py | 60 ++++++++++++++++++++++++++++++++++++++
3 files changed, 66 insertions(+), 53 deletions(-)
create mode 100644 hawkmoth/util/__init__.py
create mode 100644 hawkmoth/util/doccompat.py
diff --git a/hawkmoth/hawkmoth.py b/hawkmoth/hawkmoth.py
index 6a1d34f..92b8740 100755
--- a/hawkmoth/hawkmoth.py
+++ b/hawkmoth/hawkmoth.py
@@ -44,6 +44,7 @@
from clang.cindex import SourceLocation, SourceRange
from clang.cindex import TokenKind, TokenGroup
+from hawkmoth.util import doccompat
def is_doc_comment(comment):
return comment.startswith('/**') and comment != '/**/'
@@ -65,54 +66,6 @@ def indent(string, prefix):
def wrap_blank_lines(string):
return '\n' + string + '\n'
-# Basic Javadoc/Doxygen/kernel-doc import
-#
-# FIXME: One of the design goals of Hawkmoth is to keep things simple.
There's a
-# fine balance between sticking to that goal and adding compat code to
-# facilitate any kind of migration to Hawkmoth. The compat code could be
turned
-# into a fairly simple plugin architecture, with some basic compat builtins,
and
-# the users could still extend the compat features to fit their specific
needs.
-def compat_convert(comment, mode):
- # FIXME: try to preserve whitespace better
-
- if mode == 'javadoc-basic' or mode == 'javadoc-liberal':
- # @param
- comment = re.sub(r"(?m)^([ \t]*)@param([
\t]+)([a-zA-Z0-9_]+|\.\.\.)([ \t]+)",
- "\n\\1:param\\2\\3:\\4", comment)
- # @param[direction]
- comment = re.sub(r"(?m)^([ \t]*)@param\[([^]]*)\]([
\t]+)([a-zA-Z0-9_]+|\.\.\.)([ \t]+)",
- "\n\\1:param\\3\\4: *(\\2)* \\5", comment)
- # @return
- comment = re.sub(r"(?m)^([ \t]*)@returns?([ \t]+|$)",
- "\n\\1:return:\\2", comment)
- # @code/@endcode blocks. Works if the code is indented.
- comment = re.sub(r"(?m)^([ \t]*)@code([ \t]+|$)",
- "\n::\n", comment)
- comment = re.sub(r"(?m)^([ \t]*)@endcode([ \t]+|$)",
- "\n", comment)
- # Ignore @brief.
- comment = re.sub(r"(?m)^([ \t]*)@brief[ \t]+", "\n\\1", comment)
-
- # Ignore groups
- comment = re.sub(r"(?m)^([ \t]*)@(defgroup|addtogroup)[
\t]+[a-zA-Z0-9_]+[ \t]*",
- "\n\\1", comment)
- comment = re.sub(r"(?m)^([ \t]*)@(ingroup|{|}).*", "\n", comment)
-
- if mode == 'javadoc-liberal':
- # Liberal conversion of any @tags, will fail for @code etc. but don't
- # care.
- comment = re.sub(r"(?m)^([ \t]*)@([a-zA-Z0-9_]+)([ \t]+)",
- "\n\\1:\\2:\\3", comment)
-
- if mode == 'kernel-doc':
- # Basic kernel-doc convert, will document struct members as params,
etc.
- comment = re.sub(r"(?m)^([ \t]*)@(returns?|RETURNS?):([ \t]+|$)",
- "\n\\1:return:\\3", comment)
- comment = re.sub(r"(?m)^([ \t]*)@([a-zA-Z0-9_]+|\.\.\.):([ \t]+)",
- "\n\\1:param \\2:\\3", comment)
-
- return comment
-
def pass1(tu, top_level_comments, comments):
cursor = None
current_comment = None
@@ -195,7 +148,7 @@ def parse(filename, **options):
# parse the file, get comments
pass1(tu, top_level_comments, comments)
- # FIXME: strip_comment, compat_convert, and the C Domain directive all
+ # FIXME: strip_comment, doccompat.convert, and the C Domain directive all
# change the number of lines in output. This impacts the error reporting
via
# meta['line']. Adjust meta to take this into account.
@@ -206,7 +159,7 @@ def parse(filename, **options):
continue
doc_comment = strip_comment(comment.spelling)
- doc_comment = compat_convert(doc_comment, options.get('compat'))
+ doc_comment = doccompat.convert(doc_comment, options.get('compat'))
doc_comment = wrap_blank_lines(doc_comment)
meta = { 'line': comment.extent.start.line }
@@ -271,7 +224,7 @@ def parse(filename, **options):
kind=str(cursor.kind),
name=cursor.spelling)
- doc_comment = compat_convert(doc_comment, options.get('compat'))
+ doc_comment = doccompat.convert(doc_comment, options.get('compat'))
doc_comment = indent(doc_comment, ' ')
doc_comment = wrap_blank_lines(doc_comment)
@@ -312,7 +265,7 @@ def parse(filename, **options):
sep='.',
member=c.spelling)
- doc_comment = compat_convert(doc_comment,
options.get('compat'))
+ doc_comment = doccompat.convert(doc_comment,
options.get('compat'))
doc_comment = indent(doc_comment, ' ')
doc_comment = wrap_blank_lines(doc_comment)
@@ -336,7 +289,7 @@ def parse(filename, **options):
# FIXME: parent enum name?
cdom = '.. c:macro:: {name}\n'.format(name=c.spelling)
- doc_comment = compat_convert(doc_comment,
options.get('compat'))
+ doc_comment = doccompat.convert(doc_comment,
options.get('compat'))
doc_comment = indent(doc_comment, ' ')
doc_comment = wrap_blank_lines(doc_comment)
diff --git a/hawkmoth/util/__init__.py b/hawkmoth/util/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/hawkmoth/util/doccompat.py b/hawkmoth/util/doccompat.py
new file mode 100644
index 0000000..e687bc4
--- /dev/null
+++ b/hawkmoth/util/doccompat.py
@@ -0,0 +1,60 @@
+# Copyright (c) 2016-2017, Jani Nikula <jani@xxxxxxxxxx>
+# Licensed under the terms of BSD 2-Clause, see LICENSE for details.
+"""
+Alternative docstring syntax
+============================
+
+This module abstracts different compatibility options converting different
+syntaxes into 'native' reST ones.
+"""
+
+import re
+
+# Basic Javadoc/Doxygen/kernel-doc import
+#
+# FIXME: One of the design goals of Hawkmoth is to keep things simple.
There's a
+# fine balance between sticking to that goal and adding compat code to
+# facilitate any kind of migration to Hawkmoth. The compat code could be
turned
+# into a fairly simple plugin architecture, with some basic compat builtins,
and
+# the users could still extend the compat features to fit their specific
needs.
+def convert(comment, mode):
+ """Convert documentation from a supported syntax into reST."""
+ # FIXME: try to preserve whitespace better
+
+ if mode == 'javadoc-basic' or mode == 'javadoc-liberal':
+ # @param
+ comment = re.sub(r"(?m)^([ \t]*)@param([
\t]+)([a-zA-Z0-9_]+|\.\.\.)([ \t]+)",
+ "\n\\1:param\\2\\3:\\4", comment)
+ # @param[direction]
+ comment = re.sub(r"(?m)^([ \t]*)@param\[([^]]*)\]([
\t]+)([a-zA-Z0-9_]+|\.\.\.)([ \t]+)",
+ "\n\\1:param\\3\\4: *(\\2)* \\5", comment)
+ # @return
+ comment = re.sub(r"(?m)^([ \t]*)@returns?([ \t]+|$)",
+ "\n\\1:return:\\2", comment)
+ # @code/@endcode blocks. Works if the code is indented.
+ comment = re.sub(r"(?m)^([ \t]*)@code([ \t]+|$)",
+ "\n::\n", comment)
+ comment = re.sub(r"(?m)^([ \t]*)@endcode([ \t]+|$)",
+ "\n", comment)
+ # Ignore @brief.
+ comment = re.sub(r"(?m)^([ \t]*)@brief[ \t]+", "\n\\1", comment)
+
+ # Ignore groups
+ comment = re.sub(r"(?m)^([ \t]*)@(defgroup|addtogroup)[
\t]+[a-zA-Z0-9_]+[ \t]*",
+ "\n\\1", comment)
+ comment = re.sub(r"(?m)^([ \t]*)@(ingroup|{|}).*", "\n", comment)
+
+ if mode == 'javadoc-liberal':
+ # Liberal conversion of any @tags, will fail for @code etc. but don't
+ # care.
+ comment = re.sub(r"(?m)^([ \t]*)@([a-zA-Z0-9_]+)([ \t]+)",
+ "\n\\1:\\2:\\3", comment)
+
+ if mode == 'kernel-doc':
+ # Basic kernel-doc convert, will document struct members as params,
etc.
+ comment = re.sub(r"(?m)^([ \t]*)@(returns?|RETURNS?):([ \t]+|$)",
+ "\n\\1:return:\\3", comment)
+ comment = re.sub(r"(?m)^([ \t]*)@([a-zA-Z0-9_]+|\.\.\.):([ \t]+)",
+ "\n\\1:param \\2:\\3", comment)
+
+ return comment
--
2.20.1
