From: William S F. <ws...@fu...> - 2008-03-06 22:29:04
|
Nitro wrote: >> Regarding Idea 2 I am not sure if it's really worth a summer of coding if >> I'd go the way of using the doxygen XML output. It sounds like I'd >> have to >> write some tool which converts the xml to a swig .i file full of >> %features. These would be parsed and then put into the parse tree. Later >> on the language modules can extract the necessary information out. >> Writing >> a doxygen parser especially for SWIG does not seem a good way to do this >> to me. Doxygen supports a myriad of different syntaxes and it can also >> parse cpp and not just h files. When doxygen gains features in the future >> then they'd have to be duplicated in the swig parser. This doesn't sound >> favourable to me. Code reuse is better than code duplication. > > I can see this gets more difficult if the documentation generator should > also take things like typemaps applied to input arguments and such into > account. So just copying the C++ comments won't work in some cases. Some > in typemaps might do something like numinputs = 0. Then there's also > OUTPUT and custom user typemaps will also interfere with this (accepting > completely objects from the target language than the ones accepted in > the c++ code). > It might also be difficult to do things like > > %extend SomeClass > { > /** > * This a method extended in C > * @param foo some number > */ > void someMethod(int foo) > { > } > } > > If the doxygen XML way was used then doxygen would have to parse some > pseudo c++ code generated by swig from the %extend statement. A built-in > parser would make this easier, I don't think it would be worth it though. > So in the end there are probably many more complications than I > anticipated. So it might be enough to fill the summer :-) > > -Matthias > I for one would like to see this idea implemented. Indeed the solution might not necessarily just involve customising SWIG. Doxygen's XML output is certainly worth considering. Perhaps we could have a doxygen 'target language', where the doxygen comments are extracted and output in a C++ style class, eg: template <typename T> class SomeClass { public: // xyz has a C++ comment void xyz() { ... } }; %extend SomeClass { /** * This a method extended in C * @param foo some number */ void someMethod(int foo) { } } %template(SomeClassInt) SomeClass<int>; Would generate: class SomeClassInt { public: /** xyz has a C++ comment */ void xyz(); /** * This a method extended in C * @param foo some number */ void someMethod(int foo); }; This can be run through doxygen to generate documentation in one of its many formats. Only downside is that it doesn't support the same languages as SWIG and some languages require the documentation to be part of the code. Anyway, there are probably a number of solutions to this problem, but really, the important step is to get SWIG to parse and store the C/C++/Doxygen comments into the parse tree. William |