Menu
▾
▴
[Swig-cvs] SF.net SVN: swig:[10844] branches/gsoc2008-cherylfoil/Source
|
From: <gri...@us...> - 2008-09-12 11:21:42
|
Revision: 10844
http://swig.svn.sourceforge.net/swig/?rev=10844&view=rev
Author: gringostarr
Date: 2008-09-12 11:21:40 +0000 (Fri, 12 Sep 2008)
Log Message:
-----------
Multiple documentation sections are now concatted into one where there are various overloads for methods with the same name.
Modified Paths:
--------------
branches/gsoc2008-cherylfoil/Source/DoxygenTranslator/src/JavaDocConverter.cpp
branches/gsoc2008-cherylfoil/Source/DoxygenTranslator/src/PyDocConverter.cpp
branches/gsoc2008-cherylfoil/Source/DoxygenTranslator/src/PyDocConverter.h
branches/gsoc2008-cherylfoil/Source/Modules/python.cxx
Modified: branches/gsoc2008-cherylfoil/Source/DoxygenTranslator/src/JavaDocConverter.cpp
===================================================================
--- branches/gsoc2008-cherylfoil/Source/DoxygenTranslator/src/JavaDocConverter.cpp 2008-09-12 11:20:58 UTC (rev 10843)
+++ branches/gsoc2008-cherylfoil/Source/DoxygenTranslator/src/JavaDocConverter.cpp 2008-09-12 11:21:40 UTC (rev 10844)
@@ -128,8 +128,6 @@
return false;
std::list <DoxygenEntity> entityList = DoxygenParser().createTree(Char(documentation));
- Delete(documentation);
-
entityList.sort(CompareDoxygenEntities());
if(debug){
Modified: branches/gsoc2008-cherylfoil/Source/DoxygenTranslator/src/PyDocConverter.cpp
===================================================================
--- branches/gsoc2008-cherylfoil/Source/DoxygenTranslator/src/PyDocConverter.cpp 2008-09-12 11:20:58 UTC (rev 10843)
+++ branches/gsoc2008-cherylfoil/Source/DoxygenTranslator/src/PyDocConverter.cpp 2008-09-12 11:21:40 UTC (rev 10844)
@@ -9,8 +9,9 @@
#include "PyDocConverter.h"
#include "DoxygenParser.h"
+#include <sstream>
+#include <vector>
#include <iostream>
-#include <sstream>
//TODO {@link} {@linkplain} {@docRoot}, and other useful doxy commands that are not a pydoc tag
PyDocConverter::PyDocConverter()
@@ -121,39 +122,91 @@
return justifyString(doxyEntity.data);
}
-bool PyDocConverter::getDocumentation(Node *n, String *&documentation){
- documentation = Getattr(n,"DoxygenComment");
- if(documentation == NULL)
- return false;
-
- std::list <DoxygenEntity> entityList = DoxygenParser().createTree(Char(documentation));
- Delete(documentation);
-
- std::string pyDocString = "\"\"\"\n";
-
+std::string PyDocConverter::processEntityList(Node *n, std::list<DoxygenEntity>& entityList){
+ std::string result;
bool inParamsSection = false;
for(std::list<DoxygenEntity>::iterator entityIterator = entityList.begin(); entityIterator != entityList.end();){
- if(entityIterator->typeOfEntity.compare("param") == 0 && !inParamsSection)
- {
+ if(entityIterator->typeOfEntity.compare("param") == 0 && !inParamsSection){
inParamsSection = true;
- pyDocString += "\nArguments:\n";
+ result += "\nArguments:\n";
}
else if(entityIterator->typeOfEntity.compare("param") != 0 && inParamsSection)
inParamsSection = false;
- pyDocString += translateEntity(n, *entityIterator);
+ result += translateEntity(n, *entityIterator);
entityIterator++;
- }
+ }
+
+ return result;
+}
- pyDocString += "\n\"\"\"\n";
+bool PyDocConverter::getDocumentation(Node *n, String *&documentation){
+ std::string pyDocString, result;
- if(debug){
- std::cout << "\n---RESULT IN PYDOC---" << std::endl;
- std::cout << pyDocString;
- std::cout << std::endl;
+ // for overloaded functions we must concat documentation for underlying overloads
+ if(Checkattr(n, "kind", "function") && Getattr(n, "sym:overloaded")){
+ // rewind to the first overload
+ while (Getattr(n, "sym:previousSibling"))
+ n = Getattr(n, "sym:previousSibling");
+
+ std::vector<std::string> allDocumentation;
+
+ // for each real method (not a generated overload) append the documentation
+ while(n){
+ documentation = Getattr(n,"DoxygenComment");
+ if(!Swig_is_generated_overload(n) && documentation){
+ std::list<DoxygenEntity> entityList = DoxygenParser().createTree(Char(documentation));
+ allDocumentation.push_back(processEntityList(n, entityList));
+ }
+ n = Getattr(n, "sym:nextSibling");
+ }
+
+ // construct final documentation string
+ if(allDocumentation.size() > 1){
+ std::ostringstream concatDocString;
+ for(int realOverloadCount = 0; realOverloadCount < (int)allDocumentation.size(); realOverloadCount++){
+ concatDocString << generateDivider();
+ concatDocString << "Overload " << (realOverloadCount + 1) << ":" << std::endl;
+ concatDocString << generateDivider();
+ concatDocString << allDocumentation[realOverloadCount] << std::endl;
+ }
+ pyDocString = concatDocString.str();
+ }
+ else if (allDocumentation.size() == 1) {
+ pyDocString = *(allDocumentation.begin());
+ }
+ }
+ // for other nodes just process as normal
+ else {
+ documentation = Getattr(n,"DoxygenComment");
+ if(documentation != NULL){
+ std::list<DoxygenEntity> entityList = DoxygenParser().createTree(Char(documentation));
+ pyDocString = processEntityList(n, entityList);
+ }
}
- documentation = NewString(pyDocString.c_str());
- return true;
-}
\ No newline at end of file
+ // if we got something log the result and construct DOH string to return
+ if(pyDocString.length()) {
+ result = "\"\"\"\n" + pyDocString + "\"\"\"\n";
+
+ if(debug){
+ std::cout << "\n---RESULT IN PYDOC---" << std::endl;
+ std::cout << result;
+ std::cout << std::endl;
+ }
+
+ documentation = NewString(result.c_str());
+ return true;
+ }
+
+ return false;
+}
+
+std::string PyDocConverter::generateDivider(){
+ std::ostringstream dividerString;
+ for(int i = 0; i < DOC_STRING_LENGTH; i++)
+ dividerString << '-';
+ dividerString << std::endl;
+ return dividerString.str();
+}
Modified: branches/gsoc2008-cherylfoil/Source/DoxygenTranslator/src/PyDocConverter.h
===================================================================
--- branches/gsoc2008-cherylfoil/Source/DoxygenTranslator/src/PyDocConverter.h 2008-09-12 11:20:58 UTC (rev 10843)
+++ branches/gsoc2008-cherylfoil/Source/DoxygenTranslator/src/PyDocConverter.h 2008-09-12 11:21:40 UTC (rev 10844)
@@ -26,7 +26,15 @@
bool getDocumentation(Node *node, String *&documentation);
protected:
+
/*
+ * Process the contents of the entity list producing a documentation string.
+ * @param node The parse tree node that the entity list relates to.
+ * @param entityList The entity list to process
+ */
+ std::string processEntityList(Node *node, std::list<DoxygenEntity>& entityList);
+
+ /*
* Format the doxygen comment relating to a function or method parameter
* @param node The parse tree node that the parameter relates to.
* @param doxygenEntity The doxygen entity relating to the parameter docstring.
@@ -51,6 +59,11 @@
std::string translateSubtree( DoxygenEntity &doxygenEntity);
std::string translateEntity(Node *n, DoxygenEntity &doxyEntity);
+
+ /*
+ * Utility method to generate a diving line for a documentation string.
+ */
+ std::string generateDivider();
private:
bool debug;
Modified: branches/gsoc2008-cherylfoil/Source/Modules/python.cxx
===================================================================
--- branches/gsoc2008-cherylfoil/Source/Modules/python.cxx 2008-09-12 11:20:58 UTC (rev 10843)
+++ branches/gsoc2008-cherylfoil/Source/Modules/python.cxx 2008-09-12 11:21:40 UTC (rev 10844)
@@ -3129,30 +3129,11 @@
Printv(f_shadow, tab4, "def ", symname, "(",parms , ")", returnTypeAnnotation(n), ":", NIL);
Printv(f_shadow, "\n", NIL);
if (doxygen) {
- /*Node *documented_node = n;
- if(Getattr(n, "sym:overloaded")){
- // If the function is overloaded then this funciton is called
- // for the last one. Rewind to the first so the docstrings are
- // in order.
- while (Getattr(documented_node, "sym:previousSibling"))
- documented_node = Getattr(documented_node, "sym:previousSibling");
-
- int real_overload_count = 0;
- std::ostringstream all_documentation;
-
- // for each real method (not a generated overload) append the documentation
- while(documented_node){
- if(!is_generated_overload(documented_node) && Getattr(documented_node,"DoxygenComment")){
- all_documentation << "Overload " << ++real_overload_count << ":" << std::endl;
- all_documentation << Char(Getattr(documented_node,"DoxygenComment")) << std::endl;
- }
- documented_node = Getattr(documented_node, "sym:nextSibling");
- }
-
- char *convertedString = doxyTranslator.convert(n,const_cast< char *>(all_documentation.str().c_str()), "PYDOC");
- Printf(f_shadow, Char(pythoncode(convertedString, tab8)));
- free(convertedString);
- }*/
+ String *doxygen_comments;
+ if(DoxygenTranslator::getDocumentation(n, PyDoc, doxygen_comments)){
+ Printf(f_shadow, Char(pythoncode(doxygen_comments, tab8)));
+ Delete(doxygen_comments);
+ }
}
else if (have_docstring(n))
Printv(f_shadow, tab8, docstring(n, AUTODOC_METHOD, tab8), "\n", NIL);
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|