From: Solomon G. <sol...@gm...> - 2009-09-22 12:03:10
|
There was a mention of the doxygen branch on the swig users list a few weeks ago. I checked it out, and was able to coax some javadoc out of it. However there were three serious issues: 1. The doxygen parser uses string-tagged objects and there seems to be some confusion between the "plainstd::string" tag and the "plainstring" tag. I had to tweek a couple conditions to get any output. 2. The javadoc generator tries to sort elements of the documentation into an approved order: brief, description, param, return. Apparently, this is not quite fully implemented: The lines making up the paragraphs in the body of my descriptions were "sorted", scrambling the sentences. 3. swig directives between the doxygen comment and the function definition seem to dissasociate the two; no javadoc will be generated if e.g. an %apply comes between the comment and the definition. This is a problem for me, because some of my doc comments are more than a screen long, making it impractical to use a directive 60 lines away from where it will have its effect. An additional minor issue was that the javadoc generator attempts to re-flow text to a specific fixed width. Unfortunately, the description text is re-flowed as multiple individual lines. This creates line breaks that are arguably uglier than the problem being addressed. I am willing to try and take on some of these issues because I need the documentation capability, but I would need some direction about how to proceed.. |
From: Marko K. <mar...@is...> - 2009-09-22 14:44:15
|
Hi, Which branch did you check out? I've fixed many things in https://swig.svn.sourceforge.net/svnroot/swig/branches/gsoc2008-cherylfoil so that it works for me (Java and Python). Unfortunately the 'patch' was big and nobody reviewed it so I still have the code on my machine. If you wish I can send you a patch. Marko Solomon Gibbs wrote: > There was a mention of the doxygen branch on the swig users list a few > weeks ago. I checked it out, and was able to coax some javadoc out of > it. However there were three serious issues: > > 1. The doxygen parser uses string-tagged objects and there seems to be > some confusion between the "plainstd::string" tag and the "plainstring" > tag. I had to tweek a couple conditions to get any output. > > 2. The javadoc generator tries to sort elements of the documentation > into an approved order: brief, description, param, return. Apparently, > this is not quite fully implemented: The lines making up the paragraphs > in the body of my descriptions were "sorted", scrambling the sentences. > > 3. swig directives between the doxygen comment and the function > definition seem to dissasociate the two; no javadoc will be generated if > e.g. an %apply comes between the comment and the definition. This is a > problem for me, because some of my doc comments are more than a screen > long, making it impractical to use a directive 60 lines away from where > it will have its effect. > > An additional minor issue was that the javadoc generator attempts to > re-flow text to a specific fixed width. Unfortunately, the description > text is re-flowed as multiple individual lines. This creates line breaks > that are arguably uglier than the problem being addressed. > > I am willing to try and take on some of these issues because I need the > documentation capability, but I would need some direction about how to > proceed.. > > > ------------------------------------------------------------------------ > > ------------------------------------------------------------------------------ > Come build with us! The BlackBerry® Developer Conference in SF, CA > is the only developer event you need to attend this year. Jumpstart your > developing skills, take BlackBerry mobile applications to market and stay > ahead of the curve. Join us from November 9-12, 2009. Register now! > http://p.sf.net/sfu/devconf > > > ------------------------------------------------------------------------ > > _______________________________________________ > Swig-devel mailing list > Swi...@li... > https://lists.sourceforge.net/lists/listinfo/swig-devel |
From: William S F. <ws...@fu...> - 2009-09-22 18:19:05
|
Marko Where is the patch? I must of overlooked notification of this. We are interested in development of this functionality, so please let us know about your improvements. All I can see is an email of yours from 9 April this year, but no follow up. William Marko Klopcic wrote: > Hi, > > Which branch did you check out? I've fixed many things in > > https://swig.svn.sourceforge.net/svnroot/swig/branches/gsoc2008-cherylfoil > > so that it works for me (Java and Python). Unfortunately the 'patch' > was big and nobody reviewed it so I still have the code on my machine. > > If you wish I can send you a patch. > > > Marko > > > > Solomon Gibbs wrote: > > There was a mention of the doxygen branch on the swig users list a few > > weeks ago. I checked it out, and was able to coax some javadoc out of > > it. However there were three serious issues: > > > > 1. The doxygen parser uses string-tagged objects and there seems to be > > some confusion between the "plainstd::string" tag and the "plainstring" > > tag. I had to tweek a couple conditions to get any output. > > > > 2. The javadoc generator tries to sort elements of the documentation > > into an approved order: brief, description, param, return. Apparently, > > this is not quite fully implemented: The lines making up the paragraphs > > in the body of my descriptions were "sorted", scrambling the sentences. > > > > 3. swig directives between the doxygen comment and the function > > definition seem to dissasociate the two; no javadoc will be > generated if > > e.g. an %apply comes between the comment and the definition. This is a > > problem for me, because some of my doc comments are more than a screen > > long, making it impractical to use a directive 60 lines away from where > > it will have its effect. > > > > An additional minor issue was that the javadoc generator attempts to > > re-flow text to a specific fixed width. Unfortunately, the description > > text is re-flowed as multiple individual lines. This creates line > breaks > > that are arguably uglier than the problem being addressed. > > > > I am willing to try and take on some of these issues because I need the > > documentation capability, but I would need some direction about how to > > proceed.. > > > > > > ------------------------------------------------------------------------ > > > > > ------------------------------------------------------------------------------ > > Come build with us! The BlackBerry® Developer Conference in SF, CA > > is the only developer event you need to attend this year. Jumpstart your > > developing skills, take BlackBerry mobile applications to market and > stay > > ahead of the curve. Join us from November 9-12, 2009. Register > now! > > http://p.sf.net/sfu/devconf > > > > > > ------------------------------------------------------------------------ > > > > _______________________________________________ > > Swig-devel mailing list > > Swi...@li... > > https://lists.sourceforge.net/lists/listinfo/swig-devel > > > > ------------------------------------------------------------------------------ > Come build with us! The BlackBerry® Developer Conference in SF, CA > is the only developer event you need to attend this year. Jumpstart your > developing skills, take BlackBerry mobile applications to market and stay > ahead of the curve. Join us from November 9-12, 2009. Register > now! > http://p.sf.net/sfu/devconf > _______________________________________________ > Swig-devel mailing list > Swi...@li... > https://lists.sourceforge.net/lists/listinfo/swig-devel > |
From: Solomon G. <sol...@gm...> - 2009-09-22 20:12:43
|
On Tue, Sep 22, 2009 at 9:14 AM, Marko Klopcic <mar...@is...>wrote: > Hi, > > Which branch did you check out? I've fixed many things in > > https://swig.svn.sourceforge.net/svnroot/swig/branches/gsoc2008-cherylfoil > > so that it works for me (Java and Python). Unfortunately the 'patch' > was big and nobody reviewed it so I still have the code on my machine. > > If you wish I can send you a patch. > That is the branch I checked out. I'd be interested in this patch because I have a project ready to do a release, but it lacks documentation. > > > Marko > > > > Solomon Gibbs wrote: > > There was a mention of the doxygen branch on the swig users list a few > > weeks ago. I checked it out, and was able to coax some javadoc out of > > it. However there were three serious issues: > > > > 1. The doxygen parser uses string-tagged objects and there seems to be > > some confusion between the "plainstd::string" tag and the "plainstring" > > tag. I had to tweek a couple conditions to get any output. > > > > 2. The javadoc generator tries to sort elements of the documentation > > into an approved order: brief, description, param, return. Apparently, > > this is not quite fully implemented: The lines making up the paragraphs > > in the body of my descriptions were "sorted", scrambling the sentences. > > > > 3. swig directives between the doxygen comment and the function > > definition seem to dissasociate the two; no javadoc will be generated if > > e.g. an %apply comes between the comment and the definition. This is a > > problem for me, because some of my doc comments are more than a screen > > long, making it impractical to use a directive 60 lines away from where > > it will have its effect. > > > > An additional minor issue was that the javadoc generator attempts to > > re-flow text to a specific fixed width. Unfortunately, the description > > text is re-flowed as multiple individual lines. This creates line breaks > > that are arguably uglier than the problem being addressed. > > > > I am willing to try and take on some of these issues because I need the > > documentation capability, but I would need some direction about how to > > proceed.. > > > > > > ------------------------------------------------------------------------ > > > > > ------------------------------------------------------------------------------ > > Come build with us! The BlackBerry® Developer Conference in SF, CA > > is the only developer event you need to attend this year. Jumpstart your > > developing skills, take BlackBerry mobile applications to market and stay > > ahead of the curve. Join us from November 9-12, 2009. Register > now! > > http://p.sf.net/sfu/devconf > > > > > > ------------------------------------------------------------------------ > > > > _______________________________________________ > > Swig-devel mailing list > > Swi...@li... > > https://lists.sourceforge.net/lists/listinfo/swig-devel > > > > > ------------------------------------------------------------------------------ > Come build with us! The BlackBerry® Developer Conference in SF, CA > is the only developer event you need to attend this year. Jumpstart your > developing skills, take BlackBerry mobile applications to market and stay > ahead of the curve. Join us from November 9-12, 2009. Register now! > http://p.sf.net/sfu/devconf > _______________________________________________ > Swig-devel mailing list > Swi...@li... > https://lists.sourceforge.net/lists/listinfo/swig-devel > |
From: Olly B. <ol...@su...> - 2009-09-24 17:02:57
|
On 2009-09-22, William S Fulton <ws...@fu...> wrote: > Where is the patch? I must of overlooked notification of this. We are > interested in development of this functionality, so please let us know > about your improvements. All I can see is an email of yours from 9 April > this year, but no follow up. The patch is in the SF bugtracker, but it's large and combines reformatting changes with actual fixes. The reformatting is probably an improvement, but mixing the two makes the patch substantially harder to review and I simply haven't had the time to do so yet. I know that's not great, but I can't magically create more spare time, and it's not exactly a new idea that a patch should embody a single logical change. Cheers, Olly |
From: Solomon G. <sol...@gm...> - 2009-09-26 23:46:07
|
On Fri, Sep 25, 2009 at 9:55 AM, Marko Klopcic <mar...@is...>wrote: > > On 2009-09-22, William S Fulton <ws...@fu...> wrote: > >> Where is the patch? I must of overlooked notification of this. We are > >> interested in development of this functionality, so please let us know > >> about your improvements. All I can see is an email of yours from 9 April > >> this year, but no follow up. > > > > The patch is in the SF bugtracker, but it's large and combines > reformatting > > changes with actual fixes. The reformatting is probably an improvement, > > but mixing the two makes the patch substantially harder to review and I > > simply haven't had the time to do so yet. > > > > I know that's not great, but I can't magically create more spare time, > and > > it's not exactly a new idea that a patch should embody a single logical > > change. > > As mentioned in the last comment to the patch, I recommend to carefully > review only changes outside the DoxygenTranslator dir. There are only few > changes and almost no formatting changed. > > Files in DoxygenTranslator were changed significantly. It doesn't make > sense > to review them carefully, because comment translation was almost > useless before changes. These files also do not affect other parts of > doxygen functionality. It'd be better to compile and test it. > > I'm sorry about formatting changes, but it is much easier to understand > the code if it is readable. Next time I'll ask for a review before making > real changes :-( > Is there any way I can help with getting the patch assessed? I've checked it out and it does seem to be working better than the unpatched GSOC branch, though not completely bug-free. (Still drops some comments and passes unsanitized inputs into Printf) |
From: William S F. <ws...@fu...> - 2009-11-29 02:12:52
|
Solomon Gibbs wrote: > > > On Fri, Sep 25, 2009 at 9:55 AM, Marko Klopcic <mar...@is... > <mailto:mar...@is...>> wrote: > > > On 2009-09-22, William S Fulton <ws...@fu... > <mailto:ws...@fu...>> wrote: > >> Where is the patch? I must of overlooked notification of this. > We are > >> interested in development of this functionality, so please let > us know > >> about your improvements. All I can see is an email of yours from > 9 April > >> this year, but no follow up. > > > > The patch is in the SF bugtracker, but it's large and combines > reformatting > > changes with actual fixes. The reformatting is probably an > improvement, > > but mixing the two makes the patch substantially harder to review > and I > > simply haven't had the time to do so yet. > > > > I know that's not great, but I can't magically create more spare > time, and > > it's not exactly a new idea that a patch should embody a single > logical > > change. > > As mentioned in the last comment to the patch, I recommend to carefully > review only changes outside the DoxygenTranslator dir. There are > only few > changes and almost no formatting changed. > > Files in DoxygenTranslator were changed significantly. It doesn't > make sense > to review them carefully, because comment translation was almost > useless before changes. These files also do not affect other parts of > doxygen functionality. It'd be better to compile and test it. > > I'm sorry about formatting changes, but it is much easier to understand > the code if it is readable. Next time I'll ask for a review before > making > real changes :-( > > > Is there any way I can help with getting the patch assessed? I've > checked it out and it does seem to be working better than the unpatched > GSOC branch, though not completely bug-free. (Still drops some comments > and passes unsanitized inputs into Printf) > Anyone doing anythin with the doxygen code generation? Last I recall, I fixed the code formatting and applied some patches, but didn't hear anything after that. William |
From: Marko K. <mar...@is...> - 2009-11-30 09:08:53
|
> Anyone doing anythin with the doxygen code generation? Last I recall, I > fixed the code formatting and applied some patches, but didn't hear > anything after that. As I've said, I can try to maintain the doxygen code. At least it will convert comments from my projects :-), but I can fix other minor bugs to. I'm reading this list but I do not check Bugzilla - AFAIK bugs are submitted to the list automatically. Marko |
From: Marko K. <mar...@is...> - 2009-09-25 14:49:03
|
> On 2009-09-22, William S Fulton <ws...@fu...> wrote: >> Where is the patch? I must of overlooked notification of this. We are >> interested in development of this functionality, so please let us know >> about your improvements. All I can see is an email of yours from 9 April >> this year, but no follow up. > > The patch is in the SF bugtracker, but it's large and combines reformatting > changes with actual fixes. The reformatting is probably an improvement, > but mixing the two makes the patch substantially harder to review and I > simply haven't had the time to do so yet. > > I know that's not great, but I can't magically create more spare time, and > it's not exactly a new idea that a patch should embody a single logical > change. As mentioned in the last comment to the patch, I recommend to carefully review only changes outside the DoxygenTranslator dir. There are only few changes and almost no formatting changed. Files in DoxygenTranslator were changed significantly. It doesn't make sense to review them carefully, because comment translation was almost useless before changes. These files also do not affect other parts of doxygen functionality. It'd be better to compile and test it. I'm sorry about formatting changes, but it is much easier to understand the code if it is readable. Next time I'll ask for a review before making real changes :-( Greetings, Marko |
From: Marko K. <mar...@is...> - 2009-09-28 06:30:25
|
> Is there any way I can help with getting the patch assessed? I've > checked it out and it does seem to be working better than the unpatched > GSOC branch, though not completely bug-free. (Still drops some comments > and passes unsanitized inputs into Printf) Please send me samples, which demonstrate bugs, and I'll try to fix the code. Greetings, Marko |