Add docstrings for wxSTC methods

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@33683 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

contrib/src/stc/gen_iface.py

@@ -21,6 +21,7 @@ H_TEMPLATE    = os.path.abspath('./stc.h.in')
 CPP_TEMPLATE  = os.path.abspath('./stc.cpp.in')
 H_DEST        = os.path.abspath('../../include/wx/stc/stc.h')
 CPP_DEST      = os.path.abspath('./stc.cpp')
+DOCSTR_DEST   = os.path.abspath('../../../wxPython/contrib/stc/_stc_gendocs.i')
 
 
 # Value prefixes to convert
@@ -582,7 +583,7 @@ methodOverrideMap = {
 
 #----------------------------------------------------------------------------
 
-def processIface(iface, h_tmplt, cpp_tmplt, h_dest, cpp_dest):
+def processIface(iface, h_tmplt, cpp_tmplt, h_dest, cpp_dest, docstr_dest):
     curDocStrings = []
     values = []
     methods = []
@@ -629,7 +630,7 @@ def processIface(iface, h_tmplt, cpp_tmplt, h_dest, cpp_dest):
     data = {}
     data['VALUES'] = processVals(values)
     data['CMDS']   = processVals(cmds)
-    defs, imps = processMethods(methods)
+    defs, imps, docstrings = processMethods(methods)
     data['METHOD_DEFS'] = defs
     data['METHOD_IMPS'] = imps
 
@@ -644,6 +645,7 @@ def processIface(iface, h_tmplt, cpp_tmplt, h_dest, cpp_dest):
     # write out destination files
     open(h_dest, 'w').write(h_text)
     open(cpp_dest, 'w').write(cpp_text)
+    open(docstr_dest, 'w').write(docstrings)
 
 
 
@@ -664,6 +666,7 @@ def processVals(values):
 def processMethods(methods):
     defs = []
     imps = []
+    dstr = []
 
     for retType, name, number, param1, param2, docs in methods:
         retType = retTypeMap.get(retType, retType)
@@ -674,6 +677,11 @@ def processMethods(methods):
         if name is None:
             continue
 
+        # Build docstrings
+        st = 'DocStr(wxStyledTextCtrl::%s,\n' \
+             '"%s", "");\n' % (name, '\n'.join(docs))
+        dstr.append(st)
+        
         # Build the method definition for the .h file
         if docs:
             defs.append('')
@@ -707,7 +715,7 @@ def processMethods(methods):
         imps.append(theImp)
 
 
-    return string.join(defs, '\n'), string.join(imps, '\n')
+    return '\n'.join(defs), '\n'.join(imps), '\n'.join(dstr)
 
 
 #----------------------------------------------------------------------------
@@ -827,7 +835,7 @@ def main(args):
     # TODO: parse command line args to replace default input/output files???
 
     # Now just do it
-    processIface(IFACE, H_TEMPLATE, CPP_TEMPLATE, H_DEST, CPP_DEST)
+    processIface(IFACE, H_TEMPLATE, CPP_TEMPLATE, H_DEST, CPP_DEST, DOCSTR_DEST)
 
 
 

contrib/src/stc/stc.h.in

@@ -258,9 +258,8 @@ public:
     // Append a string to the end of the document without changing the selection.
     void AppendTextRaw(const char* text);
 
-
 #ifdef SWIG
-    %pythoncode "_stc_utf8_methods.py"
+    %%pythoncode "_stc_utf8_methods.py"
 #endif
 //----------------------------------------------------------------------
 

src/stc/gen_iface.py

@@ -21,6 +21,7 @@ H_TEMPLATE    = os.path.abspath('./stc.h.in')
 CPP_TEMPLATE  = os.path.abspath('./stc.cpp.in')
 H_DEST        = os.path.abspath('../../include/wx/stc/stc.h')
 CPP_DEST      = os.path.abspath('./stc.cpp')
+DOCSTR_DEST   = os.path.abspath('../../../wxPython/contrib/stc/_stc_gendocs.i')
 
 
 # Value prefixes to convert
@@ -582,7 +583,7 @@ methodOverrideMap = {
 
 #----------------------------------------------------------------------------
 
-def processIface(iface, h_tmplt, cpp_tmplt, h_dest, cpp_dest):
+def processIface(iface, h_tmplt, cpp_tmplt, h_dest, cpp_dest, docstr_dest):
     curDocStrings = []
     values = []
     methods = []
@@ -629,7 +630,7 @@ def processIface(iface, h_tmplt, cpp_tmplt, h_dest, cpp_dest):
     data = {}
     data['VALUES'] = processVals(values)
     data['CMDS']   = processVals(cmds)
-    defs, imps = processMethods(methods)
+    defs, imps, docstrings = processMethods(methods)
     data['METHOD_DEFS'] = defs
     data['METHOD_IMPS'] = imps
 
@@ -644,6 +645,7 @@ def processIface(iface, h_tmplt, cpp_tmplt, h_dest, cpp_dest):
     # write out destination files
     open(h_dest, 'w').write(h_text)
     open(cpp_dest, 'w').write(cpp_text)
+    open(docstr_dest, 'w').write(docstrings)
 
 
 
@@ -664,6 +666,7 @@ def processVals(values):
 def processMethods(methods):
     defs = []
     imps = []
+    dstr = []
 
     for retType, name, number, param1, param2, docs in methods:
         retType = retTypeMap.get(retType, retType)
@@ -674,6 +677,11 @@ def processMethods(methods):
         if name is None:
             continue
 
+        # Build docstrings
+        st = 'DocStr(wxStyledTextCtrl::%s,\n' \
+             '"%s", "");\n' % (name, '\n'.join(docs))
+        dstr.append(st)
+        
         # Build the method definition for the .h file
         if docs:
             defs.append('')
@@ -707,7 +715,7 @@ def processMethods(methods):
         imps.append(theImp)
 
 
-    return string.join(defs, '\n'), string.join(imps, '\n')
+    return '\n'.join(defs), '\n'.join(imps), '\n'.join(dstr)
 
 
 #----------------------------------------------------------------------------
@@ -827,7 +835,7 @@ def main(args):
     # TODO: parse command line args to replace default input/output files???
 
     # Now just do it
-    processIface(IFACE, H_TEMPLATE, CPP_TEMPLATE, H_DEST, CPP_DEST)
+    processIface(IFACE, H_TEMPLATE, CPP_TEMPLATE, H_DEST, CPP_DEST, DOCSTR_DEST)
 
 
 

src/stc/stc.h.in

@@ -258,9 +258,8 @@ public:
     // Append a string to the end of the document without changing the selection.
     void AppendTextRaw(const char* text);
 
-
 #ifdef SWIG
-    %pythoncode "_stc_utf8_methods.py"
+    %%pythoncode "_stc_utf8_methods.py"
 #endif
 //----------------------------------------------------------------------
 

wxPython/contrib/stc/_stc_docstrings.i

@@ -0,0 +1,161 @@
+/////////////////////////////////////////////////////////////////////////////
+// Name:        _stc_docstrings.i
+// Purpose:     Docstrings for the wxStyledTextCtrl.  The ones in this file
+//              are maintained by hand for those methods that are not
+//              auto-generated by gen_iface.py
+//
+// Author:      Robin Dunn
+//
+// Created:     16-April-2005
+// RCS-ID:      $Id$
+// Copyright:   (c) 2005 by Total Control Software
+// Licence:     wxWindows license
+/////////////////////////////////////////////////////////////////////////////
+
+
+// First include the autogenerated docstrings so if any of them need
+// tweaked they can be overridden below
+%include _stc_gendocs.i
+
+
+// TODO:  Class docstring
+DocStr(wxStyledTextCtrl,
+"", "");
+
+// TODO:  Main constructor
+DocStr(wxStyledTextCtrl::wxStyledTextCtrl,
+"", "");
+
+// TODO:  "Pre" constructor
+DocStr(wxStyledTextCtrl::wxStyledTextCtrl(),
+"", "");
+
+
+
+DocStr(wxStyledTextCtrl::GetCurrentLine,
+"Returns the line number of the line with the caret.", "");
+
+DocStr(wxStyledTextCtrl::StyleSetSpec,
+"Extract style settings from a spec-string which is composed of one or
+more of the following comma separated elements::
+
+     bold                    turns on bold
+     italic                  turns on italics
+     fore:[name or #RRGGBB]  sets the foreground colour
+     back:[name or #RRGGBB]  sets the background colour
+     face:[facename]         sets the font face name to use
+     size:[num]              sets the font size in points
+     eol                     turns on eol filling
+     underline               turns on underlining
+", "");
+
+DocStr(wxStyledTextCtrl::StyleSetFont,
+"Set style size, face, bold, italic, and underline attributes from the
+attributes of a `wx.Font`.", "");
+
+DocStr(wxStyledTextCtrl::StyleSetFontAttr,
+"Set all font style attributes at once.", "");
+
+DocStr(wxStyledTextCtrl::CmdKeyExecute,
+"Perform one of the operations defined by the wx.stc.STC_CMD_* constants.", "");
+
+DocStr(wxStyledTextCtrl::SetMargins,
+"Set the left and right margin in the edit area, measured in pixels.", "");
+
+DocAStr(wxStyledTextCtrl::GetSelection,
+"GetSelection(self) -> (startPos, endPos)",        
+"Retrieve the start and end positions of the current selection.", "");
+
+DocStr(wxStyledTextCtrl::PointFromPosition,
+"Retrieve the point in the window where a position is displayed.", "");
+
+DocStr(wxStyledTextCtrl::ScrollToLine,
+"Scroll enough to make the given line visible.", "");
+
+DocStr(wxStyledTextCtrl::ScrollToColumn,
+"Scroll enough to make the given column visible", "");
+
+DocStr(wxStyledTextCtrl::SendMsg,
+"Send a message to Scintilla.", "");
+
+DocStr(wxStyledTextCtrl::SetVScrollBar,
+"Set the vertical scrollbar to use instead of the one that's built-in.", "");
+
+DocStr(wxStyledTextCtrl::SetHScrollBar,
+"Set the horizontal scrollbar to use instead of the ont that's built-in.", "");
+
+DocStr(wxStyledTextCtrl::SaveFile,
+"Write the contents of the editor to filename", "");
+
+DocStr(wxStyledTextCtrl::LoadFile,
+"Load the contents of filename into the editor", "");
+
+DocStr(wxStyledTextCtrl::DoDragOver,
+"Allow for simulating a DnD DragOver.", "");
+
+DocStr(wxStyledTextCtrl::DoDropText,
+"Allow for simulating a DnD DropText.", "");
+
+DocStr(wxStyledTextCtrl::SetUseAntiAliasing,
+"Specify whether anti-aliased fonts should be used.  Will have no
+effect on some platforms, but on some (wxMac for example) can greatly
+improve performance.", "");
+
+DocStr(wxStyledTextCtrl::GetUseAntiAliasing,
+"Returns the current UseAntiAliasing setting.", "");
+
+
+
+DocStr(wxStyledTextCtrl::AddTextRaw,
+"Add text to the document at current position.  The text should be
+utf-8 encoded on unicode builds of wxPython, or can be any 8-bit text
+in ansi builds.", "");
+
+DocStr(wxStyledTextCtrl::InsertTextRaw,
+"Insert string at a position.  The text should be utf-8 encoded on
+unicode builds of wxPython, or can be any 8-bit text in ansi builds.", "");
+
+DocAStr(wxStyledTextCtrl::GetCurLineRaw,
+        "GetCurLineRaw() -> (text, index)",
+"Retrieve the text of the line containing the caret, and also the index
+of the caret on the line.  The returned value is a utf-8 encoded
+string in unicode builds of wxPython, or raw 8-bit text otherwise.", "");
+
+DocStr(wxStyledTextCtrl::GetLineRaw,
+"Retrieve the contents of a line.  The returned value is a utf-8
+encoded string in unicode builds of wxPython, or raw 8-bit text
+otherwise.", "");
+
+DocStr(wxStyledTextCtrl::GetSelectedTextRaw,
+"Retrieve the selected text.  The returned value is a utf-8 encoded
+string in unicode builds of wxPython, or raw 8-bit text otherwise.", "");
+
+DocStr(wxStyledTextCtrl::GetTextRangeRaw,
+"Retrieve a range of text.    The returned value is a utf-8 encoded
+string in unicode builds of wxPython, or raw 8-bit text otherwise.", "");
+
+DocStr(wxStyledTextCtrl::SetTextRaw,
+"Replace the contents of the document with the argument text.  The text
+should be utf-8 encoded on unicode builds of wxPython, or can be any
+8-bit text in ansi builds.", "");
+
+DocStr(wxStyledTextCtrl::GetTextRaw,
+"Retrieve all the text in the document.  The returned value is a utf-8
+encoded string in unicode builds of wxPython, or raw 8-bit text
+otherwise.", "");
+
+DocStr(wxStyledTextCtrl::AppendTextRaw,
+"Append a string to the end of the document without changing the
+selection.  The text should be utf-8 encoded on unicode builds of
+wxPython, or can be any 8-bit text in ansi builds.", "");
+
+
+
+
+// Overrides for some of the generated docstrings
+
+DocAStr(wxStyledTextCtrl::GetCurLine,
+        "GetCurLine(self) -> (text, pos)",
+"Retrieve the text of the line containing the caret, and also theindex
+of the caret on the line.", "");
+

wxPython/contrib/stc/stc.i

@@ -37,6 +37,7 @@ MAKE_CONST_WXSTRING(STCNameStr);
 
 
 %include _stc_rename.i
+%include _stc_docstrings.i
 
 MustHaveApp(wxStyledTextCtrl);
 

wxPython/setup.py

@@ -540,6 +540,8 @@ if BUILD_STC:
                             swig_args + ['-I'+STC_H, '-I'+location],
                             [opj(STC_H, 'stc.h'),
                              opj(location, "_stc_utf8_methods.py"),
+                             opj(location, "_stc_docstrings.i"),
+                             opj(location, "_stc_gendocs.i"),
                              ] + swig_deps)
 
     ext = Extension('_stc',