SWIG: Doc/Devel/plan-gsoc-2012.txt

"Fossies" - the Fresh Open Source Software Archive

Member "swig-4.1.1/Doc/Devel/plan-gsoc-2012.txt" (30 Nov 2022, 12004 Bytes) of package /linux/misc/swig-4.1.1.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. See also the last Fossies "Diffs" side-by-side code changes report for "plan-gsoc-2012.txt":

4.0.2_vs_4.1.0.

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 'https://www.doxygen.nl/manual/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 https://www.doxygen.nl/manual/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 its contents is stripped out of the output. 79 80 Doxygen tags: 81 82 All tags: -OK- 83 84 \a - translated to 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 - 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 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 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