From f60c10427081520adc73f61c9f7edf243efd26a5 Mon Sep 17 00:00:00 2001
From: Olivier Aubert <olivier.aubert@liris.cnrs.fr>
Date: Fri, 31 Jul 2009 17:58:36 +0200
Subject: [PATCH] python-ctypes: improve documentation generation

---
 bindings/python-ctypes/generate.py | 11 +++++++----
 bindings/python-ctypes/header.py   | 11 +++++++++++
 bindings/python-ctypes/override.py |  4 ++++
 3 files changed, 22 insertions(+), 4 deletions(-)

diff --git a/bindings/python-ctypes/generate.py b/bindings/python-ctypes/generate.py
index 5f8ddb792c..c7f61a00e7 100755
--- a/bindings/python-ctypes/generate.py
+++ b/bindings/python-ctypes/generate.py
@@ -207,7 +207,7 @@ def generate_header(classes=None):
 
 def convert_enum_names(enums):
     res={}
-    for (typ, name, values) in enums:
+    for (typ, name, values, comment) in enums:
         if typ != 'enum':
             raise Exception('This method only handles enums')
         pyname=re.findall('(libvlc|mediacontrol)_(.+?)(_t)?$', name)[0][1]
@@ -219,12 +219,13 @@ def convert_enum_names(enums):
     return res
 
 def generate_enums(enums):
-    for (typ, name, values) in enums:
+    for (typ, name, values, comment) in enums:
         if typ != 'enum':
             raise Exception('This method only handles enums')
         pyname=typ2class[name]
 
         print "class %s(ctypes.c_uint):" % pyname
+        print '    """%s\n    """' % comment
 
         conv={}
         # Convert symbol names
@@ -255,7 +256,7 @@ def parse_typedef(name):
     """Parse include file for typedef expressions.
 
     This generates a tuple for each typedef:
-    (type, name, value_list)
+    (type, name, value_list, comment)
     with type == 'enum' (for the moment) and value_list being a list of (name, value)
     Note that values are string, since this is intended for code generation.
     """
@@ -298,7 +299,9 @@ def parse_typedef(name):
                 else:
                     if l:
                         values.append( (l, str(i)) )
-            yield (typ, name, values)
+            comment=comment.replace('@{', '').replace('@see', 'See').replace('\ingroup', '')
+            yield (typ, name, values, comment)
+            comment=''
 
 def parse_include(name):
     """Parse include file.
diff --git a/bindings/python-ctypes/header.py b/bindings/python-ctypes/header.py
index 6684d12e41..f4a2c2db43 100755
--- a/bindings/python-ctypes/header.py
+++ b/bindings/python-ctypes/header.py
@@ -22,6 +22,17 @@
 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
 #
 
+"""This module provides bindings for the
+U{libvlc<http://wiki.videolan.org/ExternalAPI>} and
+U{MediaControl<http://wiki.videolan.org/MediaControlAPI>} APIs.
+
+You can find documentation at U{http://www.advene.org/download/python-ctypes/}.
+
+Basically, the most important class is L{Instance}, which is used to
+create a libvlc Instance. From this instance, you can then create
+L{MediaPlayer} and L{MediaListPlayer} instances.
+"""
+
 import ctypes
 import sys
 
diff --git a/bindings/python-ctypes/override.py b/bindings/python-ctypes/override.py
index 0bd39ca373..382a33a7f6 100644
--- a/bindings/python-ctypes/override.py
+++ b/bindings/python-ctypes/override.py
@@ -103,6 +103,8 @@ class MediaPlayer:
             return o
 
     def get_instance(self):
+        """Return the associated vlc.Instance.
+        """
         return self._instance
 
 class MediaListPlayer:
@@ -131,6 +133,8 @@ class MediaListPlayer:
             return o
 
     def get_instance(self):
+        """Return the associated vlc.Instance.
+        """
         return self._instance
 
 class LogIterator:
-- 
2.39.2