"Fossies" - the Fresh Open Source Software Archive

Member "swig-4.0.0/Doc/Devel/plan-gsoc-2012.txt" (26 Apr 2019, 12019 Bytes) of package /linux/privat/swig-4.0.0.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1                                                                      
    2                                                                      
    3                                                                      
    4                                              
    5                    Project Plan
    6                    ============
    7                 SWIG Code Comments
    8              Google Summer of Code 2012
    9 
   10 
   11 This document describes goals for the Google Summer of Code 2012,
   12 SWIG code documentation project.
   13 
   14 Author: Marko Klopcic, Dmitry Kabak
   15 
   16 
   17 Introduction
   18 ============
   19 
   20 The goal of this project is _not_ to translate _any_ possible Doxygen
   21 formatted comment to JavaDoc or PyDoc, but to make it possible to
   22 translate a subset of comment types in C/C++ code to
   23 JavaDoc and PyDoc. Covering all the Doxygen functionality would be to
   24 complex for the limited time. However, the code must be flexible so
   25 that implementing missing features would not require redesign of the
   26 comment handling code in SWIG.
   27 
   28 There will also be a possibility to add untranslated comments to Java
   29 and Python code (## comments, see Doxygen manual), if the user will
   30 prefer to use Doxygen on the generated code.
   31 
   32 Note:
   33 '-OK-' tick below means that the item is implemented, committed and
   34 working.
   35 
   36 Abbreviations:
   37     JD - JavaDoc
   38     PD - PyDoc
   39 
   40 
   41 Functionality
   42 =============
   43 
   44   Types of comments
   45   -----------------
   46   
   47   Note:
   48      See 'http://www.stack.nl/~dimitri/doxygen/docblocks.html' for
   49      the detailed description of Doxygen syntax and terms used in this
   50      section.
   51 
   52   1. -OK- Only JavaDoc (/** */) and Qt (/*! */) styles of comment blocks
   53      will be supported by SWIG translator.
   54 
   55   2. -OK- The following doc after members will be supported:
   56   
   57      int var; ///< Detailed description after the member
   58               //!< 
   59 
   60      int var; //!< Brief description after the member
   61 
   62      int var; ///< Brief description after the member
   63      
   64 
   65   3. -OK- Only comments before or after declaration/definition will be
   66      supported. Comments with structural commands will be ignored
   67      (warning will be written). (What about writing them to
   68      'package.info.java' for JD?)
   69   
   70 
   71   Tags
   72   ----
   73 
   74   This section contains all doxygen tags taken from 
   75   http://www.stack.nl/~dimitri/doxygen/commands.html. If a tag is
   76   marked as 'ignored', then the tag is ignored, but the text is copied
   77   to the destination documentation. 'Not implemented' means that the
   78   tag with it's contents is stripped out of the output.
   79 
   80     Doxygen tags:
   81     
   82     All tags: -OK-     
   83 
   84     \a - translated to <i></i> in JD, surrounded with _ in PD
   85     \addindex - ignored
   86     \addtogroup - ignored
   87     \anchor - ignored, not supported by JD and PD 
   88     \arg - equivalent to \li
   89     \attention - ignored
   90     \authors, \author - translated to @author in JD, 'Author:' in PD
   91     \b - <b></b> in JD, surrounded with __ in PD
   92     \brief - ignored
   93     \bug - ignored
   94     \c - translated to <code></code> in JD, ignored in PD
   95     \callgraph - ignored, not supported by JD and PD
   96     \callergraph - ignored, not supported by JD and PD
   97     \category - ignored, used only in Objective C
   98     \cite - translated to <i></i> in JD, single quotes in PD
   99     \class - ignored (structural command)
  100     \code - translated to {@code ...} in JD, ignored in PD
  101     \cond - translated to 'Conditional comment: <condition>'. Later
  102             SWIG may support definitions of conditions in config file.
  103     \copybrief - ignored. Later SWIG may support this command by
  104                   performing copy
  105     \copydetails - ignored. Later SWIG may support this command by
  106                    performing copy
  107     \copydoc - ignored. Later SWIG may support this command by
  108                performing copy
  109     \copyright - replaced with text 'Copyright' in PD and PD
  110     \date - ignored
  111     \def - ignored (structural command)
  112     \defgroup - not supported
  113     \deprecated - translated to @deprecated in JD, 'Deprecated:' in PD
  114     \details - ignored
  115     \dir - not supported
  116     \dontinclude - not supported
  117     \dot - not supported. Later SWIG may call dot and produce the graph image
  118            to include in JD and PD
  119     \dotfile - see note for \dot
  120     \e - equivalent \a
  121     \else - see note for \cond
  122     \elseif - see note for \cond
  123     \em - equivalent to \a
  124     \endcode - see note for \code
  125     \endcond - translated to 'End of conditional comment: <condition>'. Later
  126                SWIG may support definitions of conditions in config file.
  127     \enddot - see note for \dot
  128     \endhtmlonly - ignored
  129     \endif - see note for \cond
  130     \endinternal - ignored
  131     \endlatexonly - ignored
  132     \endlink - see note for \link
  133     \endmanonly - ignored
  134     \endmsc - see note for \msc
  135     \endrtfonly - ignored
  136     \endverbatim - see note for \verbatim
  137     \endxmlonly - ignored
  138     \enum - ignored (structural command)
  139     \example - translated to 'Example:' in JD and PD
  140     \exception - equivalent to throws, but translates to @exception in JD 
  141     \extends - not supported
  142     \f$ - ignored. Later swig may call LATeX to produce bitmaps with formulas
  143           to include in JD and PD
  144     \f[ - see note for \f$
  145     \f] - see note for \f$
  146     \f{ - see note for \f$
  147     \f} - see note for \f$
  148     \file - ignored (structural command)
  149     \fn - ignored (structural command)
  150     \headerfile - not supported
  151     \hideinitializer - not supported
  152     \htmlinclude - not supported
  153     \htmlonly - ignored
  154     \if - see note for \cond 
  155     \ifnot - see note for \cond
  156     \image - translated to <img/> in JD only when target=HTML, translated to
  157              'Image: filename(Title)'
  158     \implements - not supported
  159     \include - not supported
  160     \includelineno - not supported
  161     \ingroup - not supported. Later swig may print group names as plain text
  162                in comments like 'Code group: something' in both JD and PD
  163     \internal - ignored
  164     \invariant - ignored
  165     \interface - ignored (structural command)
  166     \latexonly - ignored
  167     \li - trabslated to <li></li> in JD, ignored in PD
  168     \line - not supported
  169     \link - translated to {@link ...} in JD, ignored in PD
  170     \mainpage - ignored
  171     \manonly - ignored
  172     \memberof - not supported
  173     \msc - not supported. Later SWIG may call dot and produce the graph image
  174            to include in JD and PD
  175     \mscfile - see note for \msc
  176     \n - prints the new line
  177     \name - ignored
  178     \namespace - included in package-info.java if nspace feature is enabled,
  179                  otherwise ignored, ignored in PD
  180     \nosubgrouping - ignored
  181     \note - translated to 'Note:' in both JD and PD
  182     \overload - prints 'This is an overloaded member function, provided for
  183                 convenience. It differs from the above function only in what
  184                 argument(s) it accepts.' to the output in both JD and PD
  185     \p - equivalent to \c
  186     \package - is kept same in JD (it is already a JD tag), ignored in PD
  187     \page - ignored
  188     \par - translated to <p alt='title'></p> in JD, 'Title: ...' in PD 
  189     \paragraph - ignored
  190     \param - translated to @param in JD, special formatting in PD
  191     \post - ignored
  192     \pre - ignored
  193     \private - ignored
  194     \privatesection - ignored
  195     \property - ignored
  196     \protected - ignored
  197     \protectedsection - ignored
  198     \protocol - ignored (Objective-C tag)
  199     \public - ignored
  200     \publicsection - ignored
  201     \ref - ignored, not supported by JD and PD
  202     \related - ignored 
  203     \relates - ignored
  204     \relatedalso - ignored
  205     \relatesalso - ignored
  206     \remark - translated to 'Remarks:' in both JD and PD
  207     \remarks - equivalent to remark
  208     \result - translated to @return in JD, 'Return:' in PD
  209     \return - equivalent to result
  210     \returns - equivalent to result
  211     \retval - ignored
  212     \rtfonly - ignored
  213     \sa - translated to @see in JD, 'See also:' in PD
  214     \section - not supported
  215     \see - equivalent to \sa
  216     \short - equivalent to \brief
  217     \showinitializer - not supported
  218     \since - translated to @since in JD, 'Since:' in PD
  219     \skip - not supported
  220     \skipline - not supported
  221     \snippet - not supported
  222     \struct - ignored (structural command)
  223     \subpage - not supported
  224     \subsection - not supported
  225     \subsubsection - not supported
  226     \tableofcontents - not supported
  227     \test - ignored
  228     \throw - translated to @throws in JD, 'Throws:' in PD 
  229     \throws - equivalent to \throw
  230     \todo - translated to 'TODO:' in both JD and PD
  231     \tparam - similar to \arg
  232     \typedef - ignored (structural command)
  233     \union - ignored (structural command)
  234     \until - not supported
  235     \var - ignored (structural command)
  236     \verbatim - translated to {@literal ...} in JD, ignored in PD
  237     \verbinclude - ignored
  238     \version - translated to @version in JD, 'Version:' in PD
  239     \warning - translated to 'Warning:' in both JD and PD
  240     \weakgroup - not supported
  241     \xmlonly - ignored
  242     \xrefitem - ignored
  243     \$ - this and all the others below: these commands insert single char,
  244          it is escaped as HTML char in JD, kept as-is in PD
  245     \@
  246     \\
  247     \&
  248     \~
  249     \<
  250     \>
  251     \#
  252     \%
  253     \"
  254     \.
  255     \::
  256 
  257 Optional functionality
  258 ======================
  259 
  260 That section describes some complex cases where the current code
  261 does not behave really well. Like a short to-do list of special cases.
  262 
  263 -OK- When translating functions with default parameters in swig to
  264 java, it creates overloaded functions with all the parameters
  265 except the default ones. We need to copy the doxygen comment to
  266 such functions and correct the list of @param tags.
  267 
  268 -OK- In doxygen there is a special tags (and even a special option)
  269 to create links to some code members from the current comment.
  270 Sometimes it needs a type of parameters specified because of the
  271 overloaded functions. And the same linking tags are supported in JD,
  272 but it has a completely different typesystem, so we need to translate
  273 the types of function parameters in comments also. For example:
  274 {@link MyClass#doSomething(const std::string &)}
  275 does not make sense in Java, so the type should be converted.
  276 {@link MyClass#doSomething(String)}
  277  
  278     
  279 Tests
  280 =====
  281 
  282 The following test cases will be implemented:
  283 
  284 -OK- Class comments.
  285 
  286 -OK- Struct comments.
  287 -OK- Enum comments.
  288 -OK- Function comments.
  289 -OK- Var comments.
  290 
  291 -OK- Class attributes, comment before and after declaration.
  292 -OK- Class methods, comment of parameters in function
  293   comment.
  294 -OK- Class methods, comment of parameters
  295   after parameter declaration.
  296   
  297 -OK- Struct attributes, comment before and after declaration.
  298 -OK- Struct methods, comment of parameters in function
  299   comment.
  300 -OK- Struct methods, comment of parameters 
  301   after parameter declaration.
  302 
  303 -OK- Enum items JD and Qt style, comment before items
  304 -OK- Enum items JD and Qt style, comment after items
  305 
  306 -OK- Class comment, with all supported tags.
  307 -OK- Class comment, with all doxygen tags, including
  308   ignored ones.
  309   
  310 The list of all tests, in form of shell commands to make it simple
  311 to test project by copying the text below into terminal program.
  312 make doxygen_parsing.cpptest -s
  313 make doxygen_translate.cpptest -s
  314 make doxygen_translate_all_tags.cpptest -s
  315 make doxygen_basic_translate.cpptest -s
  316 make doxygen_basic_notranslate.cpptest -s
  317 make doxygen_translate_links.cpptest -s
  318 make doxygen_tricky_constructs.cpptest -s
  319 
  320   
  321 Refactoring
  322 ===========
  323 
  324 All the code in directory _Doxygen_ should be refactored:
  325 -OK- all methods should be class members
  326 -OK- most static methods should be normal members
  327 -OK- replace C arrays of strings and sequential searches with STL data
  328   structures and algorithms.
  329 -OK- use singletons instead of class instantiaion for each comment found.
  330 
  331 
  332 Documentation
  333 =============
  334 
  335 SWIG documentation will contain:
  336 -OK- command line options
  337 -OK- list of implemented features (types and placements of comments)
  338 -OK- list of unimplemented features (types and placements of comments)
  339 -OK- list of tags and their translations (all Doxygen tags).
  340 -OK- some amount of debugging and development information
  341