From: William S F. <ws...@fu...> - 2012-08-10 17:56:36
|
Hi Dmitry I was just wondering about the Doxygen work. I read in one of the commits that all the doxygen commands can be parsed. What happens if a new doxygen command is added in the future? Will SWIG then error out or just give an unsupported doxygen command warning? I also saw the project plan describing which command are and aren't supported. Can this be put into the documentation at some point as a table of features against target language support (eg pydoc and javadoc)? William |
From: дмитрий к. <use...@gm...> - 2012-08-10 20:40:08
|
Hi William, 2012/8/10 William S Fulton <ws...@fu...> > Hi Dmitry > > I was just wondering about the Doxygen work. I read in one of the commits > that all the doxygen commands can be parsed. What happens if a new doxygen > command is added in the future? Will SWIG then error out or just give an > unsupported doxygen command warning? > Thank you for asking, it was a bug there. Right now it will silently ignore it. But I'll definitely add a warning. There is an ideology (that is stated in docs) that Doxygen parser module should never fail SWIG. So it will only produce some warnings and in worst case some info in comments will be missing. But the main code will still be generated. Also, according to the Doxygen docs, unidentified commands should be left as-is, untranslated and untouched. > > I also saw the project plan describing which command are and aren't > supported. Can this be put into the documentation at some point as a table > of features against target language support (eg pydoc and javadoc)? It's already there, see Doxygen.html in Doc/Manual folder. > > > William > -- Regards, Dmitry Kabak |
From: William S F. <ws...@fu...> - 2012-08-11 11:35:41
|
On 10/08/12 21:40, дмитрий кабак wrote: > Hi William, > > 2012/8/10 William S Fulton <ws...@fu... > <mailto:ws...@fu...>> > > Hi Dmitry > > I was just wondering about the Doxygen work. I read in one of the > commits that all the doxygen commands can be parsed. What happens if > a new doxygen command is added in the future? Will SWIG then error > out or just give an unsupported doxygen command warning? > > > Thank you for asking, it was a bug there. Right now it will silently > ignore it. But I'll definitely add a warning. There is an ideology (that > is stated in docs) that Doxygen parser module should never fail SWIG. Perfect, this is the general philosophy in SWIG overall too for standards compliant code. However, I am quite concerned about the restrictions that doxygen comments can only occur in certain places. Probably this can't be addressed during GSoC, but in order for doxygen support to be merged to trunk for general release, this restriction will need lifting. Presumably you are using different warning numbers for various types of doxygen warnings. The warning system in SWIG is rather powerful so gives a lot of power to a user to ignore/suppress warnings, so your warnings should hook into this. > So > it will only produce some warnings and in worst case some info in > comments will be missing. But the main code will still be generated. > Also, according to the Doxygen docs, unidentified commands should be > left as-is, untranslated and untouched. Nice. > > > I also saw the project plan describing which command are and aren't > supported. Can this be put into the documentation at some point as a > table of features against target language support (eg pydoc and > javadoc)? > > > It's already there, see Doxygen.html in Doc/Manual folder. Thanks, I took a look. Could you make a slight improvement to the docs at some point and provide some examples of one or two features such as nostripparams. Something else I was wondering about, have you checked the doc generation with -python -builtin? You might need to add a bit more code to support this, but it shouldn't be too hard. Could you also rename the "DoxygenComment" in the nodes to just "doxygen" as this conforms to the general naming of attributes in the parse tree and is a bit shorter? William |
From: Marko K. <mar...@is...> - 2012-08-22 11:36:02
|
Hi William, Currently code comments of all declarations (classes, functions, enums, ...) are supported, including pre and post comments. Placing of code comments at some locations may break swig with 'Error in input', but according to my experience it is not a big issue. For example, I've never encountered comments like: void /** My function. */ func(int /** my counter */ counter); (the function command is correctly processed by Doxygen, while parameter comment confuses it, producing 'func(intcounter)') Furthermore, if '-doxygen' command line option is not used, then comments are ignored and SWIG performs its job normally. I'm already using SWIG with -doxygen on our project to generate java/python with comments. My experience shows that translated comments are a great benefit for development in tools which can provide code doc on mouse hover or some other way faster than in browser (Eclipse, ipython, ...). For browser viewing I still prefer the original C++ documentation generated by Doxygen, because there are many features supported by Doxygen but not by Javadoc. IMHO merging to trunk is something to consider. Regards, Marko On 2012-08-11 1:34 PM, William S Fulton wrote: > On 10/08/12 21:40, дмитрий кабак wrote: >> Hi William, >> >> 2012/8/10 William S Fulton <ws...@fu... >> <mailto:ws...@fu...>> >> >> Hi Dmitry >> >> I was just wondering about the Doxygen work. I read in one of the >> commits that all the doxygen commands can be parsed. What happens if >> a new doxygen command is added in the future? Will SWIG then error >> out or just give an unsupported doxygen command warning? >> >> >> Thank you for asking, it was a bug there. Right now it will silently >> ignore it. But I'll definitely add a warning. There is an ideology (that >> is stated in docs) that Doxygen parser module should never fail SWIG. > Perfect, this is the general philosophy in SWIG overall too for > standards compliant code. > > However, I am quite concerned about the restrictions that doxygen > comments can only occur in certain places. Probably this can't be > addressed during GSoC, but in order for doxygen support to be merged to > trunk for general release, this restriction will need lifting. > > Presumably you are using different warning numbers for various types of > doxygen warnings. The warning system in SWIG is rather powerful so gives > a lot of power to a user to ignore/suppress warnings, so your warnings > should hook into this. > >> So >> it will only produce some warnings and in worst case some info in >> comments will be missing. But the main code will still be generated. >> Also, according to the Doxygen docs, unidentified commands should be >> left as-is, untranslated and untouched. > Nice. > >> >> I also saw the project plan describing which command are and aren't >> supported. Can this be put into the documentation at some point as a >> table of features against target language support (eg pydoc and >> javadoc)? >> >> >> It's already there, see Doxygen.html in Doc/Manual folder. > Thanks, I took a look. Could you make a slight improvement to the docs > at some point and provide some examples of one or two features such as > nostripparams. > > > Something else I was wondering about, have you checked the doc > generation with -python -builtin? You might need to add a bit more code > to support this, but it shouldn't be too hard. > > > Could you also rename the "DoxygenComment" in the nodes to just > "doxygen" as this conforms to the general naming of attributes in the > parse tree and is a bit shorter? > > William > > ------------------------------------------------------------------------------ > Live Security Virtual Conference > Exclusive live event will cover all the ways today's security and > threat landscape has changed and how IT managers can respond. Discussions > will include endpoint security, mobile security and the latest in malware > threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/ > _______________________________________________ > Swig-devel mailing list > Swi...@li... > https://lists.sourceforge.net/lists/listinfo/swig-devel |
From: William S F. <ws...@fu...> - 2012-08-31 07:21:09
|
On 22/08/12 12:17, Marko Klopcic wrote: > Hi William, > > Currently code comments of all declarations (classes, functions, enums, ...) > are supported, including pre and post comments. > Placing of code comments at some locations may break swig with 'Error in > input', > but according to my experience it is not a big issue. For example, I've > never > encountered comments like: > > void /** My function. */ func(int /** my counter */ counter); > These style C comments are common: /*************************/ struct ABC {...}; Are these successfully parsed as a non-doxygen comments? > (the function command is correctly processed by Doxygen, while parameter > comment > confuses it, producing 'func(intcounter)') > > Furthermore, if '-doxygen' command line option is not used, then > comments are > ignored and SWIG performs its job normally. > > I'm already using SWIG with -doxygen on our project to generate > java/python with comments. My experience shows that translated comments are > a great benefit for development in tools which can provide code doc on > mouse hover > or some other way faster than in browser (Eclipse, ipython, ...). > For browser viewing I still prefer the original > C++ documentation generated by Doxygen, because there are many features > supported by Doxygen but not by Javadoc. > > IMHO merging to trunk is something to consider. > If -doxygen is *not* specified, will the parser accept any doxygen comment anywhere? For example, will the parameter commenting you show above parse successfully? If this is the case, then I'll consider merging the doxygen support into trunk. But I'd want to review the code first. William |
From: Marko K. <mar...@is...> - 2012-08-31 09:21:14
|
On 2012-08-31 9:20 AM, William S Fulton wrote: > On 22/08/12 12:17, Marko Klopcic wrote: >> Hi William, >> >> Currently code comments of all declarations (classes, functions, >> enums, ...) >> are supported, including pre and post comments. >> Placing of code comments at some locations may break swig with 'Error in >> input', >> but according to my experience it is not a big issue. For example, I've >> never >> encountered comments like: >> >> void /** My function. */ func(int /** my counter */ counter); >> > These style C comments are common: > > /*************************/ > struct ABC {...}; > > Are these successfully parsed as a non-doxygen comments? > At the moment they result in an empty comment: /** * */ I or Dmitry will fix this. >> (the function command is correctly processed by Doxygen, while parameter >> comment >> confuses it, producing 'func(intcounter)') >> >> Furthermore, if '-doxygen' command line option is not used, then >> comments are >> ignored and SWIG performs its job normally. >> >> I'm already using SWIG with -doxygen on our project to generate >> java/python with comments. My experience shows that translated >> comments are >> a great benefit for development in tools which can provide code doc on >> mouse hover >> or some other way faster than in browser (Eclipse, ipython, ...). >> For browser viewing I still prefer the original >> C++ documentation generated by Doxygen, because there are many features >> supported by Doxygen but not by Javadoc. >> >> IMHO merging to trunk is something to consider. >> > If -doxygen is *not* specified, will the parser accept any doxygen > comment anywhere? For example, will the parameter commenting you show > above parse successfully? If this is the case, then I'll consider > merging the doxygen support into trunk. But I'd want to review the > code first. > Yes, it will ignore doxygen comments. If -doxygen is *not* specified, then scanner does not generate Doxygen comment related tokens. From cscanner.c: if (scan_doxygen_comments) { /* else just skip this node, to avoid crashes in parser module*/ if (strncmp(loc, "/**<", 4) == 0 || ...) { ... return DOXYGENPOSTSTRING; } if (strncmp(loc, "/**", 3) == 0 || ...) { ... return DOXYGENSTRING; } } As I've already mentioned I'm using this functionality on a real project. After the end of GSoC I found 1 bug and two other issues I'd like to improve. In a week or two this should be solved and then I'll update documentation with examples. Then it may be easier to decide whether to merge or not. Marko -- Marko Klopcic, +386 1 5680695, www.asystelectronic.si Asyst electronic d.o.o. / iSYSTEM AG Brodisce 18, SI-1236 Trzin, SLOVENIA |
From: William S F. <ws...@fu...> - 2012-08-31 20:13:59
|
On 31/08/12 10:20, Marko Klopcic wrote: > On 2012-08-31 9:20 AM, William S Fulton wrote: >> On 22/08/12 12:17, Marko Klopcic wrote: >>> Hi William, >>> >>> Currently code comments of all declarations (classes, functions, >>> enums, ...) >>> are supported, including pre and post comments. >>> Placing of code comments at some locations may break swig with 'Error in >>> input', >>> but according to my experience it is not a big issue. For example, I've >>> never >>> encountered comments like: >>> >>> void /** My function. */ func(int /** my counter */ counter); >>> >> These style C comments are common: >> >> /*************************/ >> struct ABC {...}; >> >> Are these successfully parsed as a non-doxygen comments? >> > At the moment they result in an empty comment: > /** > * > */ > I or Dmitry will fix this. >>> (the function command is correctly processed by Doxygen, while parameter >>> comment >>> confuses it, producing 'func(intcounter)') >>> >>> Furthermore, if '-doxygen' command line option is not used, then >>> comments are >>> ignored and SWIG performs its job normally. >>> >>> I'm already using SWIG with -doxygen on our project to generate >>> java/python with comments. My experience shows that translated >>> comments are >>> a great benefit for development in tools which can provide code doc on >>> mouse hover >>> or some other way faster than in browser (Eclipse, ipython, ...). >>> For browser viewing I still prefer the original >>> C++ documentation generated by Doxygen, because there are many features >>> supported by Doxygen but not by Javadoc. >>> >>> IMHO merging to trunk is something to consider. >>> >> If -doxygen is *not* specified, will the parser accept any doxygen >> comment anywhere? For example, will the parameter commenting you show >> above parse successfully? If this is the case, then I'll consider >> merging the doxygen support into trunk. But I'd want to review the >> code first. >> > Yes, it will ignore doxygen comments. If -doxygen is *not* specified, > then scanner does not generate Doxygen > comment related tokens. From cscanner.c: > > if (scan_doxygen_comments) { /* else just skip this node, to avoid > crashes in parser module*/ > if (strncmp(loc, "/**<", 4) == 0 || ...) { > ... > return DOXYGENPOSTSTRING; > } > if (strncmp(loc, "/**", 3) == 0 || ...) { > ... > return DOXYGENSTRING; > } > } > > As I've already mentioned I'm using this functionality on a real > project. After the end of GSoC > I found 1 bug and two other issues I'd like to improve. In a week or two > this should be > solved and then I'll update documentation with examples. Then it may be > easier to decide > whether to merge or not. Ah great, I'll take a closer look when you think it is ready then. William |