From: Vadim Z. <vz...@ze...> - 2014-08-11 15:15:57
|
Hello, I'm quite happy with the current state of gsoc2012-doxyge branch, it manages to generate a quite usable, and definitely useful, Python documentation for our big and complex C++ library. However there are a couple of important problems left and I'd like to discuss the first of them in this email. So, the problem is that some comments just make no sense at all in the target language context. There is really nothing that SWIG can do about this automatically, unless AI research advances much further than where it is today and we can make it actually understand the comments text. But something still needs to be done to avoid confusing Python programmers with references to shared pointers and such. The only idea I have right now is to use special Doxygen comments in the sources, e.g.: /** My function comment. Some stuff which explains what the functions does. @beginCppOnly The life time of object returned by this function is the same as life time of this object itself. @endCppOnly @beginPythonOnly The returned tuple contains foo and bar. @endPythonOnly */ This is not ideal but, again, I just don't see any other solution and at least I'm pretty sure that this one can be made to work because it's already used in some projects (without involving SWIG). My first question is whether anybody else does, i.e. do you have any better proposals about how to allow to manually specify that some part of a Doxygen comment shouldn't be used for SWIG-generated wrappers at all while some other part should only be used for them? And if no other ideas emerge, I also have a question about implementing this. Handling the hard-coded @{begin,end}XXXOnly tags shouldn't be very difficult, but I think this might be insufficiently flexible, as every project would also need to define these tags as aliases in their Doxygen configuration and inevitably some people would prefer to use other tags, with different names or different naming convention (@for_python and @end_python or whatever). So I'd prefer to somehow tell SWIG which, if any tags, should be used, but the trouble is that I don't see any nice way to do it. We could have -doxygen-include-tag and -doxygen-exclude-tag command line options, but this would be a bit ugly, especially considering that you'd have to specify 4 such options (include/exclude begin/end) all the time. I also thought of using %feature for this, but it doesn't really seem to fit. Does anyone see any natural way of specifying the tags to use? Or am I just overcomplicating things and we should hard code the tags, at least for now (and, if so, what would be your preferred tag names)? Thanks in advance for your thoughts! VZ |
From: Marko K. <mar...@is...> - 2014-08-12 06:48:20
|
<html> <head> <meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"> </head> <body bgcolor="#FFFFFF" text="#000000"> <div class="moz-cite-prefix">I'd use hard-coded tags with Doxygen naming convention. Any other solution<br> would bring more complexity than benefit, in my opinion.<br> <br> BTW, the comment below may not be the best example. The Cpp only<br> comment should be present also in Python doc, as not following the<br> object lifetime rule will crash Python.<br> <br> Greetings,<br> <br> Marko<br> <br> <br> On 2014-08-11 5:15 PM, Vadim Zeitlin wrote:<br> </div> <blockquote cite="mid:E1X...@sm..." type="cite"> <pre wrap=""> Hello, I'm quite happy with the current state of gsoc2012-doxyge branch, it manages to generate a quite usable, and definitely useful, Python documentation for our big and complex C++ library. However there are a couple of important problems left and I'd like to discuss the first of them in this email. So, the problem is that some comments just make no sense at all in the target language context. There is really nothing that SWIG can do about this automatically, unless AI research advances much further than where it is today and we can make it actually understand the comments text. But something still needs to be done to avoid confusing Python programmers with references to shared pointers and such. The only idea I have right now is to use special Doxygen comments in the sources, e.g.: /** My function comment. Some stuff which explains what the functions does. @beginCppOnly The life time of object returned by this function is the same as life time of this object itself. @endCppOnly @beginPythonOnly The returned tuple contains foo and bar. @endPythonOnly */ This is not ideal but, again, I just don't see any other solution and at least I'm pretty sure that this one can be made to work because it's already used in some projects (without involving SWIG). My first question is whether anybody else does, i.e. do you have any better proposals about how to allow to manually specify that some part of a Doxygen comment shouldn't be used for SWIG-generated wrappers at all while some other part should only be used for them? And if no other ideas emerge, I also have a question about implementing this. Handling the hard-coded @{begin,end}XXXOnly tags shouldn't be very difficult, but I think this might be insufficiently flexible, as every project would also need to define these tags as aliases in their Doxygen configuration and inevitably some people would prefer to use other tags, with different names or different naming convention (@for_python and @end_python or whatever). So I'd prefer to somehow tell SWIG which, if any tags, should be used, but the trouble is that I don't see any nice way to do it. We could have -doxygen-include-tag and -doxygen-exclude-tag command line options, but this would be a bit ugly, especially considering that you'd have to specify 4 such options (include/exclude begin/end) all the time. I also thought of using %feature for this, but it doesn't really seem to fit. Does anyone see any natural way of specifying the tags to use? Or am I just overcomplicating things and we should hard code the tags, at least for now (and, if so, what would be your preferred tag names)? Thanks in advance for your thoughts! VZ </pre> <br> <fieldset class="mimeAttachmentHeader"></fieldset> <br> <pre wrap="">------------------------------------------------------------------------------ </pre> <br> <fieldset class="mimeAttachmentHeader"></fieldset> <br> <pre wrap="">_______________________________________________ Swig-devel mailing list <a class="moz-txt-link-abbreviated" href="mailto:Swi...@li...">Swi...@li...</a> <a class="moz-txt-link-freetext" href="https://lists.sourceforge.net/lists/listinfo/swig-devel">https://lists.sourceforge.net/lists/listinfo/swig-devel</a> </pre> </blockquote> <br> <br> <pre class="moz-signature" cols="72">-- ----------------------------------------------------- Marko Klopcic, +386 1 5680695, <a class="moz-txt-link-abbreviated" href="http://www.asystelectronic.si">www.asystelectronic.si</a> Asyst electronic d.o.o. / iSYSTEM AG Brodisce 18, SI-1236 Trzin, SLOVENIA </pre> </body> </html> |
From: Vadim Z. <vz...@ze...> - 2014-08-12 13:08:20
|
On Tue, 12 Aug 2014 08:33:25 +0200 Marko Klopcic <mar...@is...> wrote: MK> I'd use hard-coded tags with Doxygen naming convention. What would be this be though? Looking at http://www.stack.nl/~dimitri/doxygen/manual/commands.html I think that we should probably use @pythononly/@endpythononly because of the existing docbookonly etc. Even though Python is a programming language and not a documentation format, of course, so a point could be made that it should use something different, e.g. @forpythononly? MK> BTW, the comment below may not be the best example. The Cpp only MK> comment should be present also in Python doc, as not following the MK> object lifetime rule will crash Python. Yes, the comment might not be the best example, but it was difficult to come up with something realistic illustrating the need for both @cpponly and @pythononly. BTW, I'd also like to have @pythoncode and @cppcode (with the corresponding @end versions), probably. Thanks for your reply! VZ |
From: Marko K. <mar...@is...> - 2014-08-12 13:50:54
|
<html> <head> <meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"> </head> <body bgcolor="#FFFFFF" text="#000000"> <div class="moz-cite-prefix"><tt>What about @</tt><tt>pydoconly, @javadoconly, @cppdoconly</tt><tt>?</tt><tt><br> </tt><tt><br> </tt><tt>Regarding '...code' tags - it seems doxygen already supports language attribute:</tt><tt><br> </tt><tt> <a class="moz-txt-link-freetext" href="http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdcode">http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdcode</a></tt><tt><br> </tt><tt><br> </tt><tt>I've never used it, though.</tt><tt> <br> </tt><tt><br> </tt><tt>Greetings,</tt><tt><br> </tt><tt><br> </tt><tt> Marko</tt><br> <br> On 2014-08-12 3:08 PM, Vadim Zeitlin wrote:<br> </div> <blockquote cite="mid:E1X...@sm..." type="cite"> <pre wrap="">On Tue, 12 Aug 2014 08:33:25 +0200 Marko Klopcic <a class="moz-txt-link-rfc2396E" href="mailto:mar...@is..."><mar...@is...></a> wrote: MK> I'd use hard-coded tags with Doxygen naming convention. What would be this be though? Looking at <a class="moz-txt-link-freetext" href="http://www.stack.nl/~dimitri/doxygen/manual/commands.html">http://www.stack.nl/~dimitri/doxygen/manual/commands.html</a> I think that we should probably use @pythononly/@endpythononly because of the existing docbookonly etc. Even though Python is a programming language and not a documentation format, of course, so a point could be made that it should use something different, e.g. @forpythononly? MK> BTW, the comment below may not be the best example. The Cpp only MK> comment should be present also in Python doc, as not following the MK> object lifetime rule will crash Python. Yes, the comment might not be the best example, but it was difficult to come up with something realistic illustrating the need for both @cpponly and @pythononly. BTW, I'd also like to have @pythoncode and @cppcode (with the corresponding @end versions), probably. Thanks for your reply! VZ </pre> <br> <fieldset class="mimeAttachmentHeader"></fieldset> <br> <pre wrap="">------------------------------------------------------------------------------ </pre> <br> <fieldset class="mimeAttachmentHeader"></fieldset> <br> <pre wrap="">_______________________________________________ Swig-devel mailing list <a class="moz-txt-link-abbreviated" href="mailto:Swi...@li...">Swi...@li...</a> <a class="moz-txt-link-freetext" href="https://lists.sourceforge.net/lists/listinfo/swig-devel">https://lists.sourceforge.net/lists/listinfo/swig-devel</a> </pre> </blockquote> <br> <br> <pre class="moz-signature" cols="72">-- ----------------------------------------------------- Marko Klopcic, +386 1 5680695, <a class="moz-txt-link-abbreviated" href="http://www.asystelectronic.si">www.asystelectronic.si</a> Asyst electronic d.o.o. / iSYSTEM AG Brodisce 18, SI-1236 Trzin, SLOVENIA </pre> </body> </html> |
From: William S F. <ws...@fu...> - 2014-08-12 18:19:43
|
On 11/08/14 16:15, Vadim Zeitlin wrote: > Hello, > > I'm quite happy with the current state of gsoc2012-doxyge branch, it > manages to generate a quite usable, and definitely useful, Python > documentation for our big and complex C++ library. However there are a > couple of important problems left and I'd like to discuss the first of them > in this email. > > So, the problem is that some comments just make no sense at all in the > target language context. There is really nothing that SWIG can do about > this automatically, unless AI research advances much further than where it > is today and we can make it actually understand the comments text. But > something still needs to be done to avoid confusing Python programmers with > references to shared pointers and such. > > The only idea I have right now is to use special Doxygen comments in the > sources, e.g.: > > /** > My function comment. > > Some stuff which explains what the functions does. > > @beginCppOnly > The life time of object returned by this function > is the same as life time of this object itself. > @endCppOnly > > @beginPythonOnly > The returned tuple contains foo and bar. > @endPythonOnly > */ > > This is not ideal but, again, I just don't see any other solution and at > least I'm pretty sure that this one can be made to work because it's > already used in some projects (without involving SWIG). > > My first question is whether anybody else does, i.e. do you have any > better proposals about how to allow to manually specify that some part of a > Doxygen comment shouldn't be used for SWIG-generated wrappers at all while > some other part should only be used for them? > > > And if no other ideas emerge, I also have a question about implementing > this. Handling the hard-coded @{begin,end}XXXOnly tags shouldn't be very > difficult, but I think this might be insufficiently flexible, as every > project would also need to define these tags as aliases in their Doxygen > configuration and inevitably some people would prefer to use other tags, > with different names or different naming convention (@for_python and > @end_python or whatever). So I'd prefer to somehow tell SWIG which, if any > tags, should be used, but the trouble is that I don't see any nice way to > do it. We could have -doxygen-include-tag and -doxygen-exclude-tag command > line options, but this would be a bit ugly, especially considering that > you'd have to specify 4 such options (include/exclude begin/end) all the > time. I also thought of using %feature for this, but it doesn't really seem > to fit. Does anyone see any natural way of specifying the tags to use? Or > am I just overcomplicating things and we should hard code the tags, at > least for now (and, if so, what would be your preferred tag names)? > > Isn't there any way to process/tweak/transform/control in some way the doxygen comments other than by command line options? I'd imagine there are plenty of ways that a user might want to modify the comments, other than a simple use or ignore all of the comment. There ought to be a generic doxygen feature matching to do comment customisations. I'd imagine it would use SWIG's %feature, or something akin to it, so that customisations can be done on a per symbol level. Do you know if there is much documentation for users? William |
From: Vadim Z. <vz...@ze...> - 2014-08-13 13:49:18
|
On Tue, 12 Aug 2014 19:19:33 +0100 William S Fulton <ws...@fu...> wrote: WSF> Isn't there any way to process/tweak/transform/control in some way the WSF> doxygen comments other than by command line options? Sorry, I'm not sure what do you mean. Currently there is no way to tweak the comments at all, neither by command line options nor in any other way. WSF> I'd imagine there are plenty of ways that a user might want to modify WSF> the comments, other than a simple use or ignore all of the comment. WSF> There ought to be a generic doxygen feature matching to do comment WSF> customisations. I'd imagine it would use SWIG's %feature, or something WSF> akin to it, so that customisations can be done on a per symbol level. How would this work, exactly? Even taking the simplest possible example in which we'd like to exclude some part of the comment which is C++-specific from Python documentation, how could you possibly describe what needs to be done using SWIG %feature? I just don't see it... WSF> Do you know if there is much documentation for users? Well, there is https://github.com/vadz/swig/blob/doxygen/Doc/Manual/Doxygen.html but it doesn't say anything about this because nothing like this currently exists. The only thing you can do right now is, indeed, to "ignore all of the comment" by using (Python-specific, I don't think anything like this exists for Java) %feature("docstring") to override it. Please let me know if I completely missed your point (which is the impression I have right now...). Thanks, VZ |
From: Vadim Z. <vz...@ze...> - 2014-08-13 13:54:44
|
On Wed, 13 Aug 2014 15:49:04 +0200 I wrote: VZ> WSF> Do you know if there is much documentation for users? VZ> VZ> Well, there is VZ> VZ> https://github.com/vadz/swig/blob/doxygen/Doc/Manual/Doxygen.html Just a better view of the same file: https://rawgit.com/vadz/swig/doxygen/Doc/Manual/Doxygen.html VZ |
From: William S F. <ws...@fu...> - 2014-08-20 22:30:59
|
On 13/08/14 14:49, Vadim Zeitlin wrote: > On Tue, 12 Aug 2014 19:19:33 +0100 William S Fulton < > ws...@fu...> wrote: > > WSF> Isn't there any way to process/tweak/transform/control in some way > the > WSF> doxygen comments other than by command line options? > > Sorry, I'm not sure what do you mean. Currently there is no way to tweak > the comments at all, neither by command line options nor in any other way. > > WSF> I'd imagine there are plenty of ways that a user might want to modify > WSF> the comments, other than a simple use or ignore all of the comment. > WSF> There ought to be a generic doxygen feature matching to do comment > WSF> customisations. I'd imagine it would use SWIG's %feature, or something > WSF> akin to it, so that customisations can be done on a per symbol level. > > How would this work, exactly? Even taking the simplest possible example > in > which we'd like to exclude some part of the comment which is C++-specific > from Python documentation, how could you possibly describe what needs to be > done using SWIG %feature? I just don't see it... > > WSF> Do you know if there is much documentation for users? > > Well, there is > > https://github.com/vadz/swig/blob/doxygen/Doc/Manual/Doxygen.html > > but it doesn't say anything about this because nothing like this currently > exists. > > The only thing you can do right now is, indeed, to "ignore all of the > comment" by using (Python-specific, I don't think anything like this exists > for Java) %feature("docstring") to override it. > > Please let me know if I completely missed your point (which is the > impression I have right now...). > There are features documented such as "doxygen:nolinktranslate" and "doxygen:nostripparams" "doxygen:notranslate" to transform and modify the doxygen comments. These look like standard SWIG features, so could be used like: %feature("doxygen:nolinktranslate") Klass::Method; hence targetting individual or global symbols (as SWIG features were designed to do). A generic doxygen tag ignore could be implemented: %feature("doxygen:ignoretag", "pythononly:endpythononly"); This is be a global feature, so would apply globally, but you could equally well get it to filter out specific tags on specific symbols, such as hiding the authors for a particular function: %feature("doxygen:ignoretag", "authors") Klass::Method; As some tags have a start and an end and some do not, I suggest using something like ":" to indicate the tag is a begin...end type tag, such as "pythononly:endpythononly" above. William |
From: Vadim Z. <vz...@ze...> - 2014-08-22 17:28:54
|
On Wed, 20 Aug 2014 22:24:20 +0100 William S Fulton <ws...@fu...> wrote: WSF> A generic doxygen tag ignore could be implemented: WSF> WSF> %feature("doxygen:ignoretag", "pythononly:endpythononly"); Perhaps I'm not grasping completely how does %feature work, but AFAICS this is not ideal because I want to be able to ignore multiple tags but the next occurrence of %feature would overwrite the previous one. So it seems to me that we'd rather need an uglier %feature("doxygen:ignore:tag1"); %feature("doxygen:ignore:tag2"); We could still also have %feature("doxygen:ignore:begintag:endtag"); of course, but I don't see how could we use the same feature name for different tags, am I missing anything? Thanks, VZ |
From: William S F. <ws...@fu...> - 2014-08-22 23:16:58
|
On 22 August 2014 18:28, Vadim Zeitlin <vz...@ze...> wrote: > On Wed, 20 Aug 2014 22:24:20 +0100 William S Fulton < > ws...@fu...> wrote: > > WSF> A generic doxygen tag ignore could be implemented: > WSF> > WSF> %feature("doxygen:ignoretag", "pythononly:endpythononly"); > > Perhaps I'm not grasping completely how does %feature work, but AFAICS > this is not ideal because I want to be able to ignore multiple tags but > the next occurrence of %feature would overwrite the previous one. So it > seems to me that we'd rather need an uglier > > %feature("doxygen:ignore:tag1"); > %feature("doxygen:ignore:tag2"); > > We could still also have > > %feature("doxygen:ignore:begintag:endtag"); > > of course, but I don't see how could we use the same feature name for > different tags, am I missing anything? > > Not at all. I overlooked the need to ignore multiple tags. We could take the same approach as %warnfilter and use a comma separated list. Some examples: %feature("doxygen:ignore", "tag1"); %feature("doxygen:ignore", "tag2"); %feature("doxygen:ignore", "tag1,tag2"); %feature("doxygen:ignore", "begintag:endtag,tag1,tag2"); But then it isn't too user friendly with regard to adding in multiple tag ignores, as you'd have to build up the list of tags to ignore if you want to handle a particular symbol differently to say a global rule. Overall, this is probably no good. The problem with the syntax you suggested, is that the feature names are not variable, I'm pretty sure they are all known at compile time. If we introduce a variable number of names, we'd need add in some support functions to get the list of all the feature:doxygen:xxxx. Probably this isn't a big deal because I'd presume the list of tags attached to each node is somehow stored elsewhere, so you could iterate through them all calling Getattr("feature:doxygen:" + tagname). But for tags that have a start and an end, then you'd need to a variable name lookup. We could circumvent this problem, by using alternative syntax, such as: %feature("doxygen:ignore:begintag", end="endtag"); This results in the following in the parse tree: | feature:doxygen:ignore:begintag:end - "endtag" | feature:doxygen:ignore:begintag - "1" so if Getattr("feature:ignore:" + tagname) works, you can call Getattr("feature:ignore" + tagname + ":end") to get the name of the end tag. Putting this into a macro is probably the way forward: #define %doxygenignore(TAG) %feature("doxygen:ignore:" ## TAG) and I think with some vararg macro jiggery pokery, you can add in the optional end attribute. William |
From: Vadim Z. <vz...@ze...> - 2014-08-23 00:26:28
|
On Sat, 23 Aug 2014 00:16:12 +0100 William S Fulton <ws...@fu...> wrote: WSF> On 22 August 2014 18:28, Vadim Zeitlin <vz...@ze...> wrote: WSF> WSF> > On Wed, 20 Aug 2014 22:24:20 +0100 William S Fulton < WSF> > ws...@fu...> wrote: WSF> > WSF> > WSF> A generic doxygen tag ignore could be implemented: WSF> > WSF> WSF> > WSF> %feature("doxygen:ignoretag", "pythononly:endpythononly"); WSF> > WSF> > Perhaps I'm not grasping completely how does %feature work, but AFAICS WSF> > this is not ideal because I want to be able to ignore multiple tags but WSF> > the next occurrence of %feature would overwrite the previous one. So it WSF> > seems to me that we'd rather need an uglier WSF> > WSF> > %feature("doxygen:ignore:tag1"); WSF> > %feature("doxygen:ignore:tag2"); WSF> > WSF> > We could still also have WSF> > WSF> > %feature("doxygen:ignore:begintag:endtag"); WSF> > WSF> > of course, but I don't see how could we use the same feature name for WSF> > different tags, am I missing anything? WSF> > WSF> Not at all. I overlooked the need to ignore multiple tags. WSF> WSF> We could take the same approach as %warnfilter and use a comma separated WSF> list. Some examples: WSF> WSF> %feature("doxygen:ignore", "tag1"); WSF> %feature("doxygen:ignore", "tag2"); WSF> %feature("doxygen:ignore", "tag1,tag2"); WSF> WSF> %feature("doxygen:ignore", "begintag:endtag,tag1,tag2"); WSF> WSF> But then it isn't too user friendly with regard to adding in multiple tag WSF> ignores, as you'd have to build up the list of tags to ignore if you want WSF> to handle a particular symbol differently to say a global rule. Overall, WSF> this is probably no good. I guess we agree anyhow but, just in case, another scenario I had in mind was temporarily/locally ignoring some tag. E.g. consider what happens if some .i file, possibly included by another one, wants to ignore some tag occurring in Doxygen comments of its declarations without affecting the including file -- there is no easy way to do it with such approach. WSF> The problem with the syntax you suggested, is that the feature names are WSF> not variable, I'm pretty sure they are all known at compile time. If we WSF> introduce a variable number of names, we'd need add in some support WSF> functions to get the list of all the feature:doxygen:xxxx. Actually, as you write below, we don't. WSF> Probably this isn't a big deal because I'd presume the list of tags WSF> attached to each node is somehow stored elsewhere, so you could WSF> iterate through them all calling Getattr("feature:doxygen:" + tagname). Exactly. I only need to test for the presence of specific features, there is no need to get the list of all of them. I do agree that this is a pretty unusual way of using %feature and this is exactly why I hesitated to propose doing it like this initially. WSF> But for tags that have a start and an end, then you'd need to a WSF> variable name lookup. We could circumvent this problem, by using WSF> alternative syntax, such as: WSF> WSF> %feature("doxygen:ignore:begintag", end="endtag"); WSF> WSF> This results in the following in the parse tree: WSF> WSF> | feature:doxygen:ignore:begintag:end - "endtag" WSF> | feature:doxygen:ignore:begintag - "1" WSF> WSF> so if Getattr("feature:ignore:" + tagname) works, you can call WSF> Getattr("feature:ignore" + tagname + ":end") to get the name of the end tag. This would work, I think. I had in mind an even simpler solution with just using a different name for the pairs of tags, but I think your is nicer, thanks! I also should say that we actually need more flexibility than just ignoring tags, there are at least the following cases: 1. Just ignore the tag, do nothing else. Example: we use @method to indicate that a function shouldn't be mapped to a property in C# even though it starts with "Get" prefix (we map all functions with such names to properties by default). 2. Ignore the tag with an argument following it. Example: we use "@iterator name" to make the method with the given name usable for iterating over a COM (yes, it's still used...) collection. 3. Ignore the tag with an _optional_ argument following it. Example: in addition to @method, we also have @property tag which can be used to map a function which does not start with "Get" to a property in C#. Usually it's used alone but sometimes the name of the function is not an appropriate name for the property, so we also use it as "@property name" in a few places. 4. Ignore everything between begin and end pair of tags. Example: @onlyforcpp/@endonlyforcpp discussed before. 5. Ignore the tags themselves but *preserve* everything between them. Example: @onlyforpython/@endonlyforpython also discussed before. What do you think should we do about this? Just use extra attributes? E.g. something like this: 1. %feature("doxygen:ignore:method"); 2. %feature("doxygen:ignore:iterator", argument="yes"); 3. %feature("doxygen:ignore:property", argument="optional"); 4. %feature("doxygen:ignore:onlyforcpp", end="endonlyforcpp", contents="ignore"); 5. %feature("doxygen:ignore:onlyforpython", end="endonlyforpython", contents="include"); ? Or would you have some better ideas? Thanks again, VZ |
From: Vadim Z. <vz...@ze...> - 2014-08-26 23:05:15
|
On Sat, 23 Aug 2014 02:26:18 +0200 I wrote: VZ> On Sat, 23 Aug 2014 00:16:12 +0100 William S Fulton <ws...@fu...> wrote: ... VZ> WSF> But for tags that have a start and an end, then you'd need to a VZ> WSF> variable name lookup. We could circumvent this problem, by using VZ> WSF> alternative syntax, such as: VZ> WSF> VZ> WSF> %feature("doxygen:ignore:begintag", end="endtag"); ... VZ> This would work, I think. I had in mind an even simpler solution with just VZ> using a different name for the pairs of tags, but I think your is nicer, thanks! VZ> VZ> I also should say that we actually need more flexibility than just VZ> ignoring tags, there are at least the following cases: ... just the tag, tag + argument or block tag with or without contents ... Finally I've implemented the following syntax, best shown with an example: ---------------------------------------------------------------------------- %module d %feature("doxygen:ignore:ignored"); %feature("doxygen:ignore:unknown", argument="line"); %feature("doxygen:ignore:forcpponly", block=1); %feature("doxygen:ignore:beginPythonOnly", end="endPythonOnly", contents="parse"); /** Some brief comment. @unknown Foo @forcpponly This is C++-specific. @endforcpponly @beginPythonOnly This is specific to @b Python. @endPythonOnly @ignored */ void func(); ///< @unknown Bar ---------------------------------------------------------------------------- which results in this output (condensing whitespace): ---------------------------------------------------------------------------- def func(): r""" Some brief comment. This is specific to **Python**. """ return _d.func() ---------------------------------------------------------------------------- The semantics should hopefully be clear enough, but here is the summary of the syntax: - By default, "doxygen:ignore:tag" just ignores the given tag. - If "argument" attribute is specified, everything until the end of line is ignored too (this is the only possible "argument" value currently, but I chose an extensible syntax for this because "word" or "paragraph" would also make sense here and could be easily added in the future if needed). - If "block=1" or "end" attributes are specified, this is a block tag and not a simple one. In this case, "argument" is not allowed, but "contents" is and specifies whether the tag contents should be parsed. By default contents is ignored, and, as above, I chose flexible syntax here as it would also make sense to have "copy" for verbatim-like custom tags here (but this is not implemented currently). - If "end" is not given, but "block" is, the end tag is constructed by prefixing "end" to the tag name, as per Doxygen convention (all its block tags are of \foo..\endfoo variety). If there are no objections, I'm going to finish this (i.e. write more tests and docs) soon, please let me know if you'd like me to change anything, I'd prefer to do it now rather than later. TIA, VZ |
From: William S F. <ws...@fu...> - 2014-08-28 19:16:44
|
On 27 August 2014 00:04, Vadim Zeitlin <vz...@ze...> wrote: > On Sat, 23 Aug 2014 02:26:18 +0200 I wrote: > > VZ> On Sat, 23 Aug 2014 00:16:12 +0100 William S Fulton < > ws...@fu...> wrote: > ... > VZ> WSF> But for tags that have a start and an end, then you'd need to a > VZ> WSF> variable name lookup. We could circumvent this problem, by using > VZ> WSF> alternative syntax, such as: > VZ> WSF> > VZ> WSF> %feature("doxygen:ignore:begintag", end="endtag"); > ... > VZ> This would work, I think. I had in mind an even simpler solution with > just > VZ> using a different name for the pairs of tags, but I think your is > nicer, thanks! > VZ> > VZ> I also should say that we actually need more flexibility than just > VZ> ignoring tags, there are at least the following cases: > ... just the tag, tag + argument or block tag with or without contents ... > > Finally I've implemented the following syntax, best shown with an example: > > > ---------------------------------------------------------------------------- > %module d > > %feature("doxygen:ignore:ignored"); > %feature("doxygen:ignore:unknown", argument="line"); > %feature("doxygen:ignore:forcpponly", block=1); > %feature("doxygen:ignore:beginPythonOnly", end="endPythonOnly", > contents="parse"); > > /** > Some brief comment. > > @unknown Foo > > @forcpponly > This is C++-specific. > @endforcpponly > > @beginPythonOnly > This is specific to @b Python. > @endPythonOnly > > @ignored > */ > void func(); ///< @unknown Bar > > ---------------------------------------------------------------------------- > > which results in this output (condensing whitespace): > > > ---------------------------------------------------------------------------- > def func(): > r""" > Some brief comment. > > This is specific to **Python**. > """ > return _d.func() > > ---------------------------------------------------------------------------- > > The semantics should hopefully be clear enough, but here is the summary of > the syntax: > > - By default, "doxygen:ignore:tag" just ignores the given tag. > > - If "argument" attribute is specified, everything until the end of line > is ignored too (this is the only possible "argument" value currently, but > I chose an extensible syntax for this because "word" or "paragraph" would > also make sense here and could be easily added in the future if needed). > > Excuse my ignorance on doxygen syntax, but are there tags which are not a line tag or a block tag? Surely a tag is either one line without an end tag or multiple lines finished by an end tag. > - If "block=1" or "end" attributes are specified, this is a block tag and > not a simple one. In this case, "argument" is not allowed, but "contents" > is and specifies whether the tag contents should be parsed. By default > contents is ignored, and, as above, I chose flexible syntax here as it > would also make sense to have "copy" for verbatim-like custom tags here > (but this is not implemented currently). > > I'm not sure I follow what "contents" does and not parsing the contents of a tag. Also what did you have in min "copy" would do? I'm also thinking that a generic syntax needs to be agreed to handle tags within a doxygen comment. The functionality applied to tags specified by the syntax ought to be made expandable/generic which I think is what the "contents" is doing?? So currently we have only been talking about "doxygen:ignore", I was thinking we ought to have "doxygen:xxx" where xxx is some other function transformation applied to the contents of the doxygen comment, perhaps something like push it through a tool like sed, or something really clever like translate it into another spoken language like Spanish. Or parse/not parse the contents, so - If "end" is not given, but "block" is, the end tag is constructed by > prefixing "end" to the tag name, as per Doxygen convention (all its block > tags are of \foo..\endfoo variety). > > I'm very much in favour of minimal syntax wherever possible (SWIG is way too complex as is stands). I'd rather a simple syntax with one way of doing something, over having multiple (convenience) syntax to achieve the same thing. Any convenience syntax that a user wants should be achievable via the preprocessor. We should ensure this too in the design of the doxygen syntax. Hence, I think you should drop the "block" syntax and instead of: %feature("doxygen:ignore:forcpponly", block=1); just have the more verbose: %feature("doxygen:ignore:forcpponly", end="endforcpponly"); If there are no objections, I'm going to finish this (i.e. write more > tests and docs) soon, please let me know if you'd like me to change > anything, I'd prefer to do it now rather than later. > Sorry, I couldn't get back sooner. William |
From: Vadim Z. <vz...@ze...> - 2014-08-28 22:08:20
|
On Thu, 28 Aug 2014 20:15:41 +0100 William S Fulton <ws...@fu...> wrote: WSF> > ---------------------------------------------------------------------------- WSF> > %module d WSF> > WSF> > %feature("doxygen:ignore:ignored"); WSF> > %feature("doxygen:ignore:unknown", argument="line"); WSF> > %feature("doxygen:ignore:forcpponly", block=1); WSF> > %feature("doxygen:ignore:beginPythonOnly", end="endPythonOnly", WSF> > contents="parse"); WSF> > WSF> > /** WSF> > Some brief comment. WSF> > WSF> > @unknown Foo WSF> > WSF> > @forcpponly WSF> > This is C++-specific. WSF> > @endforcpponly WSF> > WSF> > @beginPythonOnly WSF> > This is specific to @b Python. WSF> > @endPythonOnly WSF> > WSF> > @ignored WSF> > */ WSF> > void func(); ///< @unknown Bar WSF> > WSF> > ---------------------------------------------------------------------------- WSF> > WSF> > which results in this output (condensing whitespace): WSF> > WSF> > WSF> > ---------------------------------------------------------------------------- WSF> > def func(): WSF> > r""" WSF> > Some brief comment. WSF> > WSF> > This is specific to **Python**. WSF> > """ WSF> > return _d.func() WSF> > WSF> > ---------------------------------------------------------------------------- WSF> > WSF> > The semantics should hopefully be clear enough, but here is the summary of WSF> > the syntax: WSF> > WSF> > - By default, "doxygen:ignore:tag" just ignores the given tag. WSF> > WSF> > - If "argument" attribute is specified, everything until the end of line WSF> > is ignored too (this is the only possible "argument" value currently, but WSF> > I chose an extensible syntax for this because "word" or "paragraph" would WSF> > also make sense here and could be easily added in the future if needed). WSF> > WSF> Excuse my ignorance on doxygen syntax, but are there tags which are not a WSF> line tag or a block tag? Surely a tag is either one line without an end tag WSF> or multiple lines finished by an end tag. No, as the explanation in the beginning of the Doxygen commands documentation[1] says, Each argument has a certain range: * If <sharp> braces are used the argument is a single word. * If (round) braces are used the argument extends until the end of the line on which the command was found. * If {curly} braces are used the argument extends until the next paragraph. Paragraphs are delimited by a blank line or by a section indicator. If in addition to the above argument specifiers [square] brackets are used the argument is optional. So far I've only implemented "(round)" case which I called "line" because this is enough for my needs. But if anybody needs "<word>" or "{para}" cases later, they could be easily added too. WSF> > - If "block=1" or "end" attributes are specified, this is a block tag and WSF> > not a simple one. In this case, "argument" is not allowed, but "contents" WSF> > is and specifies whether the tag contents should be parsed. By default WSF> > contents is ignored, and, as above, I chose flexible syntax here as it WSF> > would also make sense to have "copy" for verbatim-like custom tags here WSF> > (but this is not implemented currently). WSF> > WSF> I'm not sure I follow what "contents" does and not parsing the contents of WSF> a tag. "Contents" is everything between the start tag and the end tag. In the example above you have two examples of such block tags, @forcpponly/@endforcpponly and @beginPythonOnly/@endPythonOnly. For the former, contents is ignored and doesn't appear in the output. For the latter, contents is parsed, i.e. Doxygen markup in it is recognized and this is how "@b Python" turns into "**Python**" in the output. WSF> Also what did you have in min "copy" would do? "copy" would copy the contents without parsing it, e.g. if you wanted to use Sphinx directives inside your Doxygen comments you could do this %feature("doxygen:ignore:forsphinxonly", block=1, contents="copy"); and then use Sphinx markup directly, without it being mangled by the translator, inside @forsphinxonly..@endforsphinxonly blocks. WSF> I'm also thinking that a generic syntax needs to be agreed to handle tags WSF> within a doxygen comment. The functionality applied to tags specified by WSF> the syntax ought to be made expandable/generic which I think is what the WSF> "contents" is doing?? Right now it doesn't ("copy" is _not_ implemented) but it could if anybody really needs it. I'm a big fan of not implementing the features that nobody uses, it's always better to have a concrete use scenario at hand. Without speaking of the fact that I'd really like to merge this branch in some time soon... WSF> So currently we have only been talking about "doxygen:ignore", I was WSF> thinking we ought to have "doxygen:xxx" where xxx is some other function WSF> transformation This would be possible, in principle, but I don't need it myself nor am I sure how exactly this would work, so I'd prefer not to do it for now. WSF> Hence, I think you should drop the "block" syntax and instead of: WSF> WSF> %feature("doxygen:ignore:forcpponly", block=1); WSF> WSF> just have the more verbose: WSF> WSF> %feature("doxygen:ignore:forcpponly", end="endforcpponly"); I thought the special syntax was justified in this case because "foo"/"endfoo" convention should be encouraged, as it's the one used by Doxygen itself, but I'll change it. Thanks for the review of the syntax and I hope I answered your questions about "contents", but if not, please let me know! VZ [1] http://www.stack.nl/~dimitri/doxygen/manual/commands.html |
From: William S F. <ws...@fu...> - 2014-08-29 19:10:05
|
On 28 August 2014 23:08, Vadim Zeitlin <vz...@ze...> wrote: > On Thu, 28 Aug 2014 20:15:41 +0100 William S Fulton < > ws...@fu...> wrote: > > WSF> > > ---------------------------------------------------------------------------- > WSF> > %module d > WSF> > > WSF> > %feature("doxygen:ignore:ignored"); > WSF> > %feature("doxygen:ignore:unknown", argument="line"); > WSF> > %feature("doxygen:ignore:forcpponly", block=1); > WSF> > %feature("doxygen:ignore:beginPythonOnly", end="endPythonOnly", > WSF> > contents="parse"); > WSF> > > WSF> > /** > WSF> > Some brief comment. > WSF> > > WSF> > @unknown Foo > WSF> > > WSF> > @forcpponly > WSF> > This is C++-specific. > WSF> > @endforcpponly > WSF> > > WSF> > @beginPythonOnly > WSF> > This is specific to @b Python. > WSF> > @endPythonOnly > WSF> > > WSF> > @ignored > WSF> > */ > WSF> > void func(); ///< @unknown Bar > WSF> > > WSF> > > ---------------------------------------------------------------------------- > WSF> > > WSF> > which results in this output (condensing whitespace): > WSF> > > WSF> > > WSF> > > ---------------------------------------------------------------------------- > WSF> > def func(): > WSF> > r""" > WSF> > Some brief comment. > WSF> > > WSF> > This is specific to **Python**. > WSF> > """ > WSF> > return _d.func() > WSF> > > WSF> > > ---------------------------------------------------------------------------- > WSF> > > WSF> > The semantics should hopefully be clear enough, but here is the > summary of > WSF> > the syntax: > WSF> > > WSF> > - By default, "doxygen:ignore:tag" just ignores the given tag. > WSF> > > WSF> > - If "argument" attribute is specified, everything until the end of > line > WSF> > is ignored too (this is the only possible "argument" value > currently, but > WSF> > I chose an extensible syntax for this because "word" or > "paragraph" would > WSF> > also make sense here and could be easily added in the future if > needed). > WSF> > > WSF> Excuse my ignorance on doxygen syntax, but are there tags which are > not a > WSF> line tag or a block tag? Surely a tag is either one line without an > end tag > WSF> or multiple lines finished by an end tag. > > No, as the explanation in the beginning of the Doxygen commands > documentation[1] says, > > Each argument has a certain range: > > * If <sharp> braces are used the argument is a single word. > * If (round) braces are used the argument extends until the end > of the line on which the command was found. > * If {curly} braces are used the argument extends until the next > paragraph. Paragraphs are delimited by a blank line or by a section > indicator. > > If in addition to the above argument specifiers [square] brackets > are used the argument is optional. > > So far I've only implemented "(round)" case which I called "line" because > this is enough for my needs. But if anybody needs "<word>" or "{para}" > cases later, they could be easily added too. > > > WSF> > - If "block=1" or "end" attributes are specified, this is a block > tag and > WSF> > not a simple one. In this case, "argument" is not allowed, but > "contents" > WSF> > is and specifies whether the tag contents should be parsed. By > default > WSF> > contents is ignored, and, as above, I chose flexible syntax here > as it > WSF> > would also make sense to have "copy" for verbatim-like custom > tags here > WSF> > (but this is not implemented currently). > WSF> > > WSF> I'm not sure I follow what "contents" does and not parsing the > contents of > WSF> a tag. > > "Contents" is everything between the start tag and the end tag. In the > example above you have two examples of such block tags, > @forcpponly/@endforcpponly and @beginPythonOnly/@endPythonOnly. For the > former, contents is ignored and doesn't appear in the output. For the > latter, contents is parsed, i.e. Doxygen markup in it is recognized and > this is how "@b Python" turns into "**Python**" in the output. > > WSF> Also what did you have in min "copy" would do? > > "copy" would copy the contents without parsing it, e.g. if you wanted to > use Sphinx directives inside your Doxygen comments you could do this > > %feature("doxygen:ignore:forsphinxonly", block=1, contents="copy"); > > and then use Sphinx markup directly, without it being mangled by the > translator, inside @forsphinxonly..@endforsphinxonly blocks. > > > > WSF> I'm also thinking that a generic syntax needs to be agreed to handle > tags > WSF> within a doxygen comment. The functionality applied to tags specified > by > WSF> the syntax ought to be made expandable/generic which I think is what > the > WSF> "contents" is doing?? > > Right now it doesn't ("copy" is _not_ implemented) but it could if anybody > really needs it. I'm a big fan of not implementing the features that nobody > uses, it's always better to have a concrete use scenario at hand. Without > speaking of the fact that I'd really like to merge this branch in some time > soon... > > WSF> So currently we have only been talking about "doxygen:ignore", I was > WSF> thinking we ought to have "doxygen:xxx" where xxx is some other > function > WSF> transformation > > This would be possible, in principle, but I don't need it myself nor am I > sure how exactly this would work, so I'd prefer not to do it for now. > > > WSF> Hence, I think you should drop the "block" syntax and instead of: > WSF> > WSF> %feature("doxygen:ignore:forcpponly", block=1); > WSF> > WSF> just have the more verbose: > WSF> > WSF> %feature("doxygen:ignore:forcpponly", end="endforcpponly"); > > I thought the special syntax was justified in this case because > "foo"/"endfoo" convention should be encouraged, as it's the one used by > Doxygen itself, but I'll change it. > > Thanks for the review of the syntax and I hope I answered your questions > about "contents", but if not, please let me know! > VZ > > [1] http://www.stack.nl/~dimitri/doxygen/manual/commands.html > > > I see, thanks for elaborating. The range of the tags is more complex than I thought and so the only thing I'd suggest is changing is the name from 'argument' to 'range' so as to use the same terminology in the doxygen explanation. Looks like you have a default for contents="copy" and argument="line" if they are not specified which seems sensible. I've another suggestion instead of using end="endSomething" or block=1 for further simplicity. How about using range="end" instead, and thus enforcing the use of the \something \endsomething syntax. So the example then becomes: %feature("doxygen:ignore:forcpponly", range="end") to ignore between \forcpponly to \endforcpponly. The possible values for range then become "end", "word", "line", "paragraph" and you're thus offering implementations for the first two. William |
From: Vadim Z. <vz...@ze...> - 2014-08-29 19:41:54
|
On Fri, 29 Aug 2014 20:03:02 +0100 William S Fulton <ws...@fu...> wrote: WSF> I've another suggestion instead of using end="endSomething" or block=1 for WSF> further simplicity. How about using range="end" instead, and thus enforcing WSF> the use of the \something \endsomething syntax. So the example then becomes: WSF> WSF> %feature("doxygen:ignore:forcpponly", range="end") to ignore between WSF> \forcpponly to \endforcpponly. WSF> WSF> The possible values for range then become "end", "word", "line", WSF> "paragraph" and you're thus offering implementations for the first two. I think this is too limiting. I know of several projects (both open source and not) that use custom tags not following the convention of \foo..\endfoo naming. I agree that this %feature is quite complex and I don't like it much neither, but I don't see how could it be made simpler without gratuitously dropping support for some reasonably use cases. Regards, VZ |
From: Vadim Z. <vz...@ze...> - 2014-09-03 13:09:47
|
On Fri, 29 Aug 2014 21:41:39 +0200 I wrote: Me> On Fri, 29 Aug 2014 20:03:02 +0100 William S Fulton <ws...@fu...> wrote: Me> Me> WSF> I've another suggestion instead of using end="endSomething" or block=1 for Me> WSF> further simplicity. How about using range="end" instead, and thus enforcing Me> WSF> the use of the \something \endsomething syntax. So the example then becomes: Me> WSF> Me> WSF> %feature("doxygen:ignore:forcpponly", range="end") to ignore between Me> WSF> \forcpponly to \endforcpponly. Me> WSF> Me> WSF> The possible values for range then become "end", "word", "line", Me> WSF> "paragraph" and you're thus offering implementations for the first two. Me> Me> I think this is too limiting. I know of several projects (both open source Me> and not) that use custom tags not following the convention of \foo..\endfoo Me> naming. Me> Me> I agree that this %feature is quite complex and I don't like it much Me> neither, but I don't see how could it be made simpler without gratuitously Me> dropping support for some reasonably use cases. Actually, I do know, but I'm not sure if this is not too artificial to be easily understandable: we could have range="..endTag" to support arbitrary end tag names. The ".." evokes, at least for me, an interval and we could even allow %feature("doxygen:ignore:forcpponly", range=".."); as a shortcut for %feature("doxygen:ignore:forcpponly", range="..endforcpponly"); Personally I rather like it, what do you think? VZ |
From: William S F. <ws...@fu...> - 2014-09-03 18:46:12
|
On 3 September 2014 14:09, Vadim Zeitlin <vz...@ze...> wrote: > On Fri, 29 Aug 2014 21:41:39 +0200 I wrote: > > Me> On Fri, 29 Aug 2014 20:03:02 +0100 William S Fulton < > ws...@fu...> wrote: > Me> > Me> WSF> I've another suggestion instead of using end="endSomething" or > block=1 for > Me> WSF> further simplicity. How about using range="end" instead, and thus > enforcing > Me> WSF> the use of the \something \endsomething syntax. So the example > then becomes: > Me> WSF> > Me> WSF> %feature("doxygen:ignore:forcpponly", range="end") to ignore > between > Me> WSF> \forcpponly to \endforcpponly. > Me> WSF> > Me> WSF> The possible values for range then become "end", "word", "line", > Me> WSF> "paragraph" and you're thus offering implementations for the > first two. > Me> > Me> I think this is too limiting. I know of several projects (both open > source > Me> and not) that use custom tags not following the convention of > \foo..\endfoo > Me> naming. > Me> > Me> I agree that this %feature is quite complex and I don't like it much > Me> neither, but I don't see how could it be made simpler without > gratuitously > Me> dropping support for some reasonably use cases. > > Actually, I do know, but I'm not sure if this is not too artificial to be > easily understandable: we could have range="..endTag" to support arbitrary > end tag names. The ".." evokes, at least for me, an interval and we could > even allow > > %feature("doxygen:ignore:forcpponly", range=".."); > > as a shortcut for > > %feature("doxygen:ignore:forcpponly", range="..endforcpponly"); > > > Personally I rather like it, what do you think? > > > While I can see the attraction of this, I don't want to see SWIG turn into a Perl-like language with obscure syntax. %feature is modelled on xml with attributes, so let's use it like originally intended, even if a bit more verbose, and use attribute names that are easily understood. I propose what I had before, but adding in a new optional attribute 'end' which if specified will override the default end tag name if range=="end". If the 'end' %feature attribute is not specified, then the doxygen end tag name is as previously discussed, that is the tag name prefixed with 'end'. Hence the following two are equivalent: %feature("doxygen:ignore:forcpponly", range="end"); %feature("doxygen:ignore:forcpponly", range="end", end="endforcpponly"); I think that provides the flexibility needed without being too complicated and fits in a bit better with normal SWIG %feature usage. Any more thoughts? William |
From: Vadim Z. <vz...@ze...> - 2014-09-03 20:03:15
|
On Wed, 3 Sep 2014 19:45:23 +0100 William S Fulton <ws...@fu...> wrote: WSF> > Actually, I do know, but I'm not sure if this is not too artificial to be WSF> > easily understandable: we could have range="..endTag" to support arbitrary WSF> > end tag names. The ".." evokes, at least for me, an interval and we could WSF> > even allow WSF> > WSF> > %feature("doxygen:ignore:forcpponly", range=".."); WSF> > WSF> > as a shortcut for WSF> > WSF> > %feature("doxygen:ignore:forcpponly", range="..endforcpponly"); WSF> > WSF> > WSF> > Personally I rather like it, what do you think? WSF> > WSF> While I can see the attraction of this, I don't want to see SWIG turn into WSF> a Perl-like language with obscure syntax. How did you know I liked Perl? ;-) WSF> %feature("doxygen:ignore:forcpponly", range="end"); WSF> %feature("doxygen:ignore:forcpponly", range="end", end="endforcpponly"); WSF> WSF> I think that provides the flexibility needed without being too WSF> complicated and fits in a bit better with normal SWIG %feature usage. WSF> Any more thoughts? This seems a bit redundant to me and while I understand that this can be seen as an advantage if XML, which is supposed to be verbose, is the model, the problem is that it makes it possible to write something inconsistent like %feature("doxygen:ignore:forcpponly", range="line", end="endforcpponly"); I can (and will have to) flag this as an error, of course, but it just seems inelegant to allow this in the first place to me. Maybe we should drop "range" and use just the "end" attribute? Then we could have end="line" (and end="word|paragraph" in the future if needed) for the current range="line", interpret end="1" as meaning that it's a tag following the standard end tag naming convention and take everything else as an explicit end tag name. Notice that this does assume that nobody is going to call their end tag "line" but it's a pretty safe assumption as "\line" is already a standard tag, and while neither "\word" nor "\paragraph" exist, I still think the chance of having custom end tags with these names is negligible. My examples from https://rawgit.com/vadz/swig/doxygen/Doc/Manual/Doxygen.html#Doxygen_features would then become %feature("doxygen:ignore:transferfull"); %feature("doxygen:ignore:compileroptions", end="line"); %feature("doxygen:ignore:forcpponly", end="1"); %feature("doxygen:ignore:beginPythonOnly", end="endPythonOnly", contents="parse"); What do you think? If you still don't like this, I'll just implement your proposal above, inconsistency and all, but having one attribute still seems preferable to me than having two of them. And while end="1" is still cryptic, I think it is already used for some other features, isn't it? Anyhow, please let me know what do you prefer and I'll do it. TIA! VZ |
From: William S F. <ws...@fu...> - 2014-09-09 19:04:17
|
On 3 September 2014 21:03, Vadim Zeitlin <vz...@ze...> wrote: > On Wed, 3 Sep 2014 19:45:23 +0100 William S Fulton < > ws...@fu...> wrote: > > WSF> > Actually, I do know, but I'm not sure if this is not too > artificial to be > WSF> > easily understandable: we could have range="..endTag" to support > arbitrary > WSF> > end tag names. The ".." evokes, at least for me, an interval and we > could > WSF> > even allow > WSF> > > WSF> > %feature("doxygen:ignore:forcpponly", range=".."); > WSF> > > WSF> > as a shortcut for > WSF> > > WSF> > %feature("doxygen:ignore:forcpponly", > range="..endforcpponly"); > WSF> > > WSF> > > WSF> > Personally I rather like it, what do you think? > WSF> > > WSF> While I can see the attraction of this, I don't want to see SWIG turn > into > WSF> a Perl-like language with obscure syntax. > > How did you know I liked Perl? ;-) > > WSF> %feature("doxygen:ignore:forcpponly", range="end"); > WSF> %feature("doxygen:ignore:forcpponly", range="end", > end="endforcpponly"); > WSF> > WSF> I think that provides the flexibility needed without being too > WSF> complicated and fits in a bit better with normal SWIG %feature usage. > WSF> Any more thoughts? > > This seems a bit redundant to me and while I understand that this can be > seen as an advantage if XML, which is supposed to be verbose, is the model, > the problem is that it makes it possible to write something inconsistent > like > > %feature("doxygen:ignore:forcpponly", range="line", > end="endforcpponly"); > > I can (and will have to) flag this as an error, of course, but it just > seems inelegant to allow this in the first place to me. > > > Maybe we should drop "range" and use just the "end" attribute? Then we > could have end="line" (and end="word|paragraph" in the future if needed) > for the current range="line", interpret end="1" as meaning that it's a tag > following the standard end tag naming convention and take everything else > as an explicit end tag name. > > Notice that this does assume that nobody is going to call their end tag > "line" but it's a pretty safe assumption as "\line" is already a standard > tag, and while neither "\word" nor "\paragraph" exist, I still think the > chance of having custom end tags with these names is negligible. > > My examples from > https://rawgit.com/vadz/swig/doxygen/Doc/Manual/Doxygen.html#Doxygen_features > would then become > > %feature("doxygen:ignore:transferfull"); > %feature("doxygen:ignore:compileroptions", end="line"); > %feature("doxygen:ignore:forcpponly", end="1"); > %feature("doxygen:ignore:beginPythonOnly", end="endPythonOnly", > contents="parse"); > > What do you think? If you still don't like this, I'll just implement your > proposal above, inconsistency and all, but having one attribute still seems > preferable to me than having two of them. And while end="1" is still > cryptic, I think it is already used for some other features, isn't it? > > Anyhow, please let me know what do you prefer and I'll do it. TIA! > > Having pondered over this, I'm not sure there is a great solution. I've never been keen on using "1" as a special value either. The crux of the problem is that we're trying to cram two bits of information into one place. I don't see the problem with the 'inconsistency' you show, it is just an optional value that is only relevant in certain circumstances. There are plenty of APIs that work like that. Anyway, I'd rather my previous proposal than your latest suggestion. If you are set on having just one attribute name, then perhaps this: %feature("doxygen:ignore:forcpponly", range="end"); %feature("doxygen:ignore:forcpponly", range="end:endforcpponly"); Where the values for range are as mentioned before, except if you use "end" and add a colon and a non-empty tag name, then the given tag name will override the default end tag name. I'll let you choose from here! William |
From: Vadim Z. <vz...@ze...> - 2014-09-10 20:11:43
|
On Tue, 9 Sep 2014 19:56:58 +0100 William S Fulton <ws...@fu...> wrote: WSF> Having pondered over this, I'm not sure there is a great solution. Me neither, unfortunately. WSF> I've never been keen on using "1" as a special value either. The crux WSF> of the problem is that we're trying to cram two bits of information WSF> into one place. But we wouldn't be even trying to do it if they were independent. The problem is that they're not. So we don't have 2 bits, actually, but rather 1.5 of them. WSF> I don't see the problem with the 'inconsistency' you show, it is just an WSF> optional value that is only relevant in certain circumstances. There are WSF> plenty of APIs that work like that. I know, but IMHO this is a typical property of bad APIs... Good syntax shouldn't allow writing something internally inconsistent in the first place. WSF> Anyway, I'd rather my previous proposal than your latest suggestion. If you WSF> are set on having just one attribute name, then perhaps this: WSF> WSF> %feature("doxygen:ignore:forcpponly", range="end"); WSF> %feature("doxygen:ignore:forcpponly", range="end:endforcpponly"); WSF> WSF> Where the values for range are as mentioned before, except if you use "end" WSF> and add a colon and a non-empty tag name, then the given tag name will WSF> override the default end tag name. Thanks, I like this much better than my own end="1"/end="endforcpponly" idea, so... WSF> I'll let you choose from here! ... I've unsurprisingly chosen to implement this one. The latest version has been pushed to Github now, please let me know if you have any comments and thanks in advance for looking at it and merging Doxygen branch! VZ |