Improve output so that the width of the docstrings can be controlled.

git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/branches/gsoc2008-cherylfoil@10841 626c5289-ae23-0410-ae9c-e8d60b6d4f22

Source/DoxygenTranslator/src/PyDocConverter.cpp

@@ -2,9 +2,6 @@
 #include <iostream>
 #include <sstream>
 
-#define APPROX_LINE_LENGTH 64//characters per line allowed
-#define TAB_SIZE 8//characters per line allowed
-
 //TODO {@link} {@linkplain} {@docRoot}, and other useful doxy commands that are not a pydoc tag
 PyDocConverter::PyDocConverter()
 {
@@ -15,7 +12,7 @@ PyDocConverter::~PyDocConverter()
 {
 }
  
-void PyDocConverter::printSortedTree(std::list <DoxygenEntity> &entityList){
+void PyDocConverter::printTree(std::list <DoxygenEntity> &entityList){
   std::list<DoxygenEntity>::iterator p = entityList.begin();
   while (p != entityList.end()){
     (*p).printEntity(0);
@@ -24,24 +21,23 @@ void PyDocConverter::printSortedTree(std::list <DoxygenEntity> &entityList){
 }
 
 std::string PyDocConverter::formatParam(Node *n, DoxygenEntity &doxygenEntity) {
-  std::string result;
   ParmList *plist = CopyParmList(Getattr(n, "parms"));
   Parm *p = NULL;
   
   DoxygenEntity& paramNameEntity = *doxygenEntity.entityList.begin();
   DoxygenEntity& paramDescriptionEntity = *(++doxygenEntity.entityList.begin());
   
+  std::string result;
+  std::string paramDescription = formatCommand(paramDescriptionEntity.data, DOC_PARAM_STRING_LENGTH);
+  
   for (p = plist; p;) {
     if(Char(Getattr(p, "name")) == paramNameEntity.data) {
       std::string name = Char(Swig_name_make(n, 0, Getattr(p, "name"), 0, 0));
       std::string type = Char(Swig_name_make(n, 0, Getattr(p, "type"), 0, 0));
       
-      std::ostringstream parameterDocString;
+      result = name + " (" + type + ") ";
-      
+      result.resize(DOC_PARAM_STRING_LENGTH - 3, ' ');
-      parameterDocString << std::endl << name << " (" << type << ") -- ";
+      result += "-- " + paramDescription.substr(DOC_PARAM_STRING_LENGTH);
-      parameterDocString << paramDescriptionEntity.data;
-      
-      result = parameterDocString.str();
       break;
     }
     p = Getattr(p, "tmap:in") ? Getattr(p, "tmap:in:next") : nextSibling(p);
@@ -51,88 +47,33 @@ std::string PyDocConverter::formatParam(Node *n, DoxygenEntity &doxygenEntity) {
   return result;
 }
 
-std::string PyDocConverter::formatCommand(std::string unformattedLine, int indent){
+std::string PyDocConverter::formatCommand(std::string documentString, int indent, int maxWidth){
-  std::string formattedLines = "\n";
+  std::ostringstream formattedString;
-  int lastPosition = 0;
+  std::string currentLine;
-  signed int i = 0;
-  bool isFirstLine  = true;
-  while (i != -1 && i < (int)unformattedLine.length()){
-    lastPosition = i;
-    if (isFirstLine){
-      i+=APPROX_LINE_LENGTH;
-    }
-    else i+=APPROX_LINE_LENGTH - indent*TAB_SIZE;
-    i = unformattedLine.find(" ", i);
   
-    if (i > 0 && i + 1 < (int)unformattedLine.length()){
+  for(std::string::iterator stringPosition = documentString.begin(); stringPosition != documentString.end(); ++stringPosition)
-      if (!isFirstLine) for (int j = 0; j < indent; j++) {
+  {
-        formattedLines.append("\t");
+    if(currentLine.length() == 0)
-        }
+      currentLine.resize(indent, ' ');
-      else {
-        isFirstLine = false;
-      }
-      formattedLines.append(unformattedLine.substr(lastPosition, i - lastPosition + 1));
-      formattedLines.append("\n");
     
+    currentLine += *stringPosition;
+      
+    if(*stringPosition == ' ' && (int)currentLine.size() >= maxWidth || (stringPosition + 1) == documentString.end())
+    {
+      formattedString << currentLine << std::endl;
+      currentLine = "";
     }
   }
-  if (lastPosition < (int)unformattedLine.length()){
-    if (!isFirstLine) {for (int j = 0; j < indent; j++) {formattedLines.append("\t");}}
-    formattedLines.append(unformattedLine.substr(lastPosition, unformattedLine.length() - lastPosition));
-  }
   
-  return formattedLines;
+  return formattedString.str();
 }
 
-/* Contains the conversions for tags
- * could probably be much more efficient...
- */
-std::string PyDocConverter::pyDocFormat(DoxygenEntity &doxygenEntity){
-  if(doxygenEntity.typeOfEntity.compare("partofdescription") == 0){
-        return doxygenEntity.data;
-    }
-  if (doxygenEntity.typeOfEntity.compare("plainstd::string") == 0){
-      return  doxygenEntity.data;
-  }
-  else if (doxygenEntity.typeOfEntity.compare("b") == 0){
-    return "<b>" + doxygenEntity.data + "</b>";
-  }
-  else if (doxygenEntity.typeOfEntity.compare("c") == 0){
-    return "<tt>" + doxygenEntity.data + "</tt>";
-  }
-  else if (doxygenEntity.typeOfEntity.compare("@") == 0){
-    return "@";
-  }
-  else if (doxygenEntity.typeOfEntity.compare("\\") == 0){
-    return "\\";
-  }
-  else if (doxygenEntity.typeOfEntity.compare("<") == 0){
-    return "&lt;";
-  }
-  else if (doxygenEntity.typeOfEntity.compare(">") == 0){
-    return "&gt;";
-  }
-  else if (doxygenEntity.typeOfEntity.compare("&") == 0){
-    return "&amp;";
-  }
-  else if (doxygenEntity.typeOfEntity.compare("#") == 0){
-    return "#";
-  }
-  else if (doxygenEntity.typeOfEntity.compare("%") == 0){
-    return "%";
-  }
-  else if (doxygenEntity.typeOfEntity.compare("~") == 0){
-    return "~";
-  }
-  return "";
-}
-
-
 std::string PyDocConverter::translateSubtree( DoxygenEntity &doxygenEntity){
   std::string returnedString;
-  if (doxygenEntity.isLeaf){ return pyDocFormat(doxygenEntity) + " ";}
+  if (doxygenEntity.isLeaf)
+    return doxygenEntity.data + " ";
   else {
-    returnedString += pyDocFormat(doxygenEntity);
+    returnedString += doxygenEntity.data;
     std::list<DoxygenEntity>::iterator p = doxygenEntity.entityList.begin();
     while (p != doxygenEntity.entityList.end()){
       returnedString+= translateSubtree(*p);
@@ -160,8 +101,10 @@ std::string PyDocConverter::translateEntity(Node *n, DoxygenEntity &doxyEntity){
   if(doxyEntity.typeOfEntity.compare("param") == 0)
     return formatParam(n, doxyEntity);
   
-  if(doxyEntity.typeOfEntity.compare("return")== 0
+  if(doxyEntity.typeOfEntity.compare("return")== 0)
-      || doxyEntity.typeOfEntity.compare("author")== 0
+    
+
+  if(doxyEntity.typeOfEntity.compare("author")== 0
     || doxyEntity.typeOfEntity.compare("param")== 0
     || doxyEntity.typeOfEntity.compare("since")== 0
     || doxyEntity.typeOfEntity.compare("version")== 0
@@ -172,20 +115,23 @@ std::string PyDocConverter::translateEntity(Node *n, DoxygenEntity &doxyEntity){
   if(doxyEntity.typeOfEntity.compare("sa")== 0)
     return formatCommand(std::string("@see\t\t" + translateSubtree(doxyEntity)), 2);
 
-  return formatCommand(pyDocFormat(doxyEntity), 0);
+  return formatCommand(doxyEntity.data, 0);
 }
 
 std::string PyDocConverter::convertToPyDoc(Node *n, std::list<DoxygenEntity> entityList){
-  entityList.sort(CompareDoxygenEntities());
+  std::string pyDocString = "\"\"\"\n";
   
-  if(debug){
+  bool inParamsSection = false;
-    std::cout << "---RESORTED LIST---" << std::endl;
-    printSortedTree(entityList);
-  }
-
-  std::string pyDocString = "\"\"\"";
   
   for(std::list<DoxygenEntity>::iterator entityIterator = entityList.begin(); entityIterator != entityList.end();){
+    if(entityIterator->typeOfEntity.compare("param") == 0 && !inParamsSection)
+    {
+      inParamsSection = true;
+      pyDocString += "\nArguments:\n";
+    }
+    else if(entityIterator->typeOfEntity.compare("param") != 0 && inParamsSection)
+      inParamsSection = false;
+    
     pyDocString += translateEntity(n, *entityIterator);
     entityIterator++;
   }
@@ -195,6 +141,7 @@ std::string PyDocConverter::convertToPyDoc(Node *n, std::list<DoxygenEntity> ent
   if(debug){
     std::cout << "\n---RESULT IN PYDOC---" << std::endl;
     std::cout << pyDocString;
+    std::cout << std::endl;
   }
   
   return pyDocString;

Source/DoxygenTranslator/src/PyDocConverter.h

@@ -6,18 +6,20 @@
 #include "swig.h"
 #include "DoxygenEntity.h"
 
+#define DOC_STRING_LENGTH	  64  // characters per line allowed
+#define DOC_PARAM_STRING_LENGTH	  30  // characters reserved for param name / type
+
 class PyDocConverter
 {
 public:
   PyDocConverter();
   std::string convertToPyDoc(Node *n, std::list <DoxygenEntity> entityList);
   ~PyDocConverter();
-  void printSortedTree(std::list <DoxygenEntity> &entityList);
+  void printTree(std::list <DoxygenEntity> &entityList);
 
 protected:
   std::string formatParam(Node *n, DoxygenEntity &doxygenEntity);
-  std::string formatCommand(std::string unformattedLine, int indent);
+  std::string formatCommand(std::string unformattedLine, int indent, int maxWidth = DOC_STRING_LENGTH);
-  std::string pyDocFormat(DoxygenEntity &doxygenEntity);
   std::string translateSubtree( DoxygenEntity &doxygenEntity);
   std::string translateEntity(Node *n, DoxygenEntity &doxyEntity);