C++ bindings: Attach documentation to enum wrapper classes.

diff --git a/bindings/cxx/ConfigKey_methods.hpp b/bindings/cxx/ConfigKey_methods.hpp
index 997a52ee4a3e264c8599e9a654faccab0b571722..00a508d6536b27588650453044b50581dc235c55 100644 (file)
--- a/bindings/cxx/ConfigKey_methods.hpp
+++ b/bindings/cxx/ConfigKey_methods.hpp
@@ -1,5 +1,10 @@
+    /** Data type used for this configuration key. */
     const DataType *get_data_type() const;
+    /** String identifier for this configuration key, suitable for CLI use. */
     string get_identifier() const;
+    /** Description of this configuration key. */
     string get_description() const;
+    /** Get configuration key by string identifier. */
     static const ConfigKey *get(string identifier);
+    /** Parse a string argument into the appropriate type for this key. */
     Glib::VariantBase parse_string(string value) const;

diff --git a/bindings/cxx/Doxyfile b/bindings/cxx/Doxyfile
index 9de1e6c53a75dff3a323abfc972973c8e57d490e..6d4b15383e16d58832a56af2af8f0f0b8a9bb6e6 100644 (file)
--- a/bindings/cxx/Doxyfile
+++ b/bindings/cxx/Doxyfile
@@ -743,7 +743,7 @@ WARN_LOGFILE           =
 # spaces.
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = include
+INPUT                  = include/libsigrok/libsigrok.hpp
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

diff --git a/bindings/cxx/QuantityFlag_methods.hpp b/bindings/cxx/QuantityFlag_methods.hpp
index 4bbe48db11397c3302865e71249cd0229850f8b6..dfb3c1e8b3fef2e184d7453fa9b367896dc1b44c 100644 (file)
--- a/bindings/cxx/QuantityFlag_methods.hpp
+++ b/bindings/cxx/QuantityFlag_methods.hpp
@@ -1,2 +1,3 @@
+       /** Get flags corresponding to a bitmask. */
        static vector<const QuantityFlag *>
                flags_from_mask(unsigned int mask);

diff --git a/bindings/cxx/enums.py b/bindings/cxx/enums.py
index bdf12bf64e6cf89f662d395da92b3766cc99878c..fdc8e8e3dcda46a68c0afeb3cdaf41a3b01e4227 100644 (file)
--- a/bindings/cxx/enums.py
+++ b/bindings/cxx/enums.py
@@ -27,15 +27,15 @@ index_file = sys.argv[1]
 dirname = os.path.dirname(os.path.realpath(__file__))
 
 mapping = dict([
-    ('sr_loglevel', 'LogLevel'),
-    ('sr_packettype', 'PacketType'),
-    ('sr_mq', 'Quantity'),
-    ('sr_unit', 'Unit'),
-    ('sr_mqflag', 'QuantityFlag'),
-    ('sr_configkey', 'ConfigKey'),
-    ('sr_datatype', 'DataType'),
-    ('sr_channeltype', 'ChannelType'),
-    ('sr_trigger_matches', 'TriggerMatchType')])
+    ('sr_loglevel', ('LogLevel', 'Log verbosity level')),
+    ('sr_packettype', ('PacketType', 'Type of datafeed packet')),
+    ('sr_mq', ('Quantity', 'Measured quantity')),
+    ('sr_unit', ('Unit', 'Unit of measurement')),
+    ('sr_mqflag', ('QuantityFlag', 'Flag applied to measured quantity')),
+    ('sr_configkey', ('ConfigKey', 'Configuration key')),
+    ('sr_datatype', ('DataType', 'Configuration data type')),
+    ('sr_channeltype', ('ChannelType', 'Channel type')),
+    ('sr_trigger_matches', ('TriggerMatchType', 'Trigger match type'))])
 
 index = ElementTree.parse(index_file)
 
@@ -68,6 +68,7 @@ for file in (header, code):
 
 # Template for beginning of class declaration and public members.
 header_public_template = """
+/** {brief} */
 class SR_API {classname} : public EnumValue<enum {enumname}>
 {{
 public:
@@ -94,18 +95,26 @@ const {classname} *{classname}::get(int id)
 }}
 """
 
-for enum, classname in classes.items():
+def get_text(node):
+    return str.join('\n\n',
+        [p.text.rstrip() for p in node.findall('para')])
+
+for enum, (classname, classbrief) in classes.items():
 
     enum_name = enum.find('name').text
-    member_names = [m.find('name').text for m in enum.findall('enumvalue')]
+    members = enum.findall('enumvalue')
+    member_names = [m.find('name').text for m in members]
     trimmed_names = [re.sub("^SR_[A-Z]+_", "", n) for n in member_names]
+    briefs = [get_text(m.find('briefdescription')) for m in members]
 
     # Begin class and public declarations
     print >> header, header_public_template.format(
-        classname=classname, enumname=enum_name)
+        brief=classbrief, classname=classname, enumname=enum_name)
 
     # Declare public pointers for each enum value
-    for trimmed_name in trimmed_names:
+    for trimmed_name, brief in zip(trimmed_names, briefs):
+        if brief:
+            print >> header, '\t/** %s */' % brief
         print >> header, '\tstatic const %s * const %s;' % (
             classname, trimmed_name)