From 5a391c79c3db13f8ee8e1a4279373b3652c7d4d0 Mon Sep 17 00:00:00 2001
From: Matthew Brush <mbrush@codebrainz.ca>
Date: Sun, 7 Feb 2016 10:06:02 -0800
Subject: [PATCH] Replace comments and asserts with doc-comments and doc-tests

---
 scripts/gen-api-gtkdoc.py | 32 +++++++++++++++++++++-----------
 1 file changed, 21 insertions(+), 11 deletions(-)

diff --git a/scripts/gen-api-gtkdoc.py b/scripts/gen-api-gtkdoc.py
index e80a1ae12..26a8bbd8b 100755
--- a/scripts/gen-api-gtkdoc.py
+++ b/scripts/gen-api-gtkdoc.py
@@ -6,23 +6,33 @@ import re
 from lxml import etree
 from optparse import OptionParser
 
-# " asd\nxxx  " => "asd xxx"
 def normalize_text(s):
-    return s.replace("\n", " ").lstrip().rstrip()
+    r"""
+    Normalizes whitespace in text.
 
-assert(normalize_text("asd xxx") == "asd xxx")
-assert(normalize_text(" asd\nxxx  ") == "asd xxx")
+    >>> normalize_text("asd xxx")
+    'asd xxx'
+    >>> normalize_text(" asd\nxxx  ")
+    'asd xxx'
+    """
+    return s.replace("\n", " ").strip()
 
-# doxygen records some definitions in C++ style, fix those
-# "bool FooBar::flag" => "bool flag"
-# void(* _GeanyObjectClass::project_open) (GKeyFile *keyfile) => void(* project_open) (GKeyFile *keyfile)
 CXX_NAMESPACE_RE = re.compile(r'[_a-zA-Z][_0-9a-zA-Z]*::')
 def fix_definition(s):
-    return CXX_NAMESPACE_RE.sub(r"", s);
+    """
+    Removes C++ name qualifications from some definitions.
+
+    For example:
 
-assert(fix_definition("bool flag") == "bool flag")
-assert(fix_definition("bool FooBar::flag") == "bool flag")
-assert(fix_definition("void(* _GeanyObjectClass::project_open) (GKeyFile *keyfile)") == "void(* project_open) (GKeyFile *keyfile)")
+    >>> fix_definition("bool flag")
+    'bool flag'
+    >>> fix_definition("bool FooBar::flag")
+    'bool flag'
+    >>> fix_definition("void(* _GeanyObjectClass::project_open) (GKeyFile *keyfile)")
+    'void(* project_open) (GKeyFile *keyfile)'
+
+    """
+    return CXX_NAMESPACE_RE.sub(r"", s);
 
 class AtAt(object):
 
-- 
2.11.4.GIT