doxygen-users

Re: [Doxygen-users] Linking to functions with long parameter lists

[Clemens F. <c....@os...>]

Hi Daniel.

You ask for a line-continuation feature in doxygen. 
You mean something like the backslash for the C-preprocessor, don't 
you?

Well, seems that nobody knows such feature for doxygen, including me.

But I have an idea that once again is based on regular expressions 
(regex):

1.
Assuming that you have a very long line you want to break into 
smaller ones, you write something like the following in your source 
code:

first part         /*%*/ 
second part   /*%*/
third part       /*%*/

After each of those /*%*/ will be a new-line character.
The /*%*/ is just a proposal, you can use whatever marker you want.

2.
You use a regex tool like SED together with the INPUT_FILTER option 
of doxygen to search for   /*%*/+linebreak   and remove it including 
the linebreak from the doxygen input. 
Note that this regular expression filtering does not change your 
source files.

3.
Doxygen should only see one big line. 

That's it. Theoretically. It is just an idea, I have not tested.

I have posted several messages this year, that deal about regular 
expressions and the usage of the SED tool together with doxygen.

If you really want to dig into this, please let me hear whether it 
works. Good luck.

Clemens


On 8 Feb 2007 at 15:53, Daniel Rubin wrote:

> Hi list!
> 
> (( First of all:  I'm new here so best of greetings to everyone! ))
> 
> I have a question/problem with doxygen concerning links to C++ class
> member functions with long parameter lists.  Linking to a specific
> overloaded version works well as long as the whole reference, say
> 
>     @see func(Type1 param1, ..., TypeN paramN)
> 
> is placed on one line.  When it is split up on multiple lines, doxygen
> obviously doesn't recognise it as function-with-parameter-list
> reference any more, as it only uses the function name for the anchor
> and unconditionally links to the first version of the overload or
> doesn't link at all.
> 
> Now I'd really like to wrap my doc comments to stay inside a
> 80-character boundary, so is there some sort of line-continuation
> support in doxygen or any other method to work around this limitation?
> 
> Any pointers would be greatly appreciated.
> 
> Have fun
> ----Daniel

Re: [Doxygen-users] Linking to functions with long parameter lists

[Daniel R. <dr...@ma...>]

Clemens Feige wrote:

> Hi Daniel.
> 
> You ask for a line-continuation feature in doxygen. 
> You mean something like the backslash for the C-preprocessor, don't 
> you?
> 
> Well, seems that nobody knows such feature for doxygen, including me.
> 
> But I have an idea that once again is based on regular expressions 
> (regex):
> 
> 1.
> Assuming that you have a very long line you want to break into 
> smaller ones, you write something like the following in your source 
> code:
> 
> first part         /*%*/ 
> second part   /*%*/
> third part       /*%*/
> 
> After each of those /*%*/ will be a new-line character.
> The /*%*/ is just a proposal, you can use whatever marker you want.
> 
> 2.
> You use a regex tool like SED together with the INPUT_FILTER option 
> of doxygen to search for   /*%*/+linebreak   and remove it including 
> the linebreak from the doxygen input. 
> Note that this regular expression filtering does not change your 
> source files.
> 
> 3.
> Doxygen should only see one big line. 
> 
> That's it. Theoretically. It is just an idea, I have not tested.

Clemens, that's just a _neat_ idea.
I wasn't aware of the INPUT_FILTER thing, never thinking I'd ever 
have to preprocess my sources with anything other than cpp.

Do you know when INPUT_FILTER is applied?  Before or after cpp?


> I have posted several messages this year, that deal about regular 
> expressions and the usage of the SED tool together with doxygen.
> 
> If you really want to dig into this, please let me hear whether it 
> works. Good luck.
> 
> Clemens
I'll give this a try shortly.

Thanks a lot, have fun
----Daniel



> On 8 Feb 2007 at 15:53, Daniel Rubin wrote:
> 
>> Hi list!
>>
>> (( First of all:  I'm new here so best of greetings to everyone! ))
>>
>> I have a question/problem with doxygen concerning links to C++ class
>> member functions with long parameter lists.  Linking to a specific
>> overloaded version works well as long as the whole reference, say
>>
>>     @see func(Type1 param1, ..., TypeN paramN)
>>
>> is placed on one line.  When it is split up on multiple lines, doxygen
>> obviously doesn't recognise it as function-with-parameter-list
>> reference any more, as it only uses the function name for the anchor
>> and unconditionally links to the first version of the overload or
>> doesn't link at all.
>>
>> Now I'd really like to wrap my doc comments to stay inside a
>> 80-character boundary, so is there some sort of line-continuation
>> support in doxygen or any other method to work around this limitation?
>>
>> Any pointers would be greatly appreciated.
>>
>> Have fun
>> ----Daniel
> 
> 
> -------------------------------------------------------------------------
> Take Surveys. Earn Cash. Influence the Future of IT
> Join SourceForge.net's Techsay panel and you'll get the chance to share your
> opinions on IT & business topics through brief surveys-and earn cash
> http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users

Re: [Doxygen-users] Linking to functions with long parameter lists

[Daniel R. <dr...@ma...>]

Daniel Rubin wrote:

> Clemens Feige wrote:
> 
>> Hi Daniel.
>>
>> You ask for a line-continuation feature in doxygen. You mean something 
>> like the backslash for the C-preprocessor, don't you?
>>
>> Well, seems that nobody knows such feature for doxygen, including me.
>>
>> But I have an idea that once again is based on regular expressions 
>> (regex):
>>
>> 1.
>> Assuming that you have a very long line you want to break into smaller 
>> ones, you write something like the following in your source code:
>>
>> first part         /*%*/ second part   /*%*/
>> third part       /*%*/
>>
>> After each of those /*%*/ will be a new-line character.
>> The /*%*/ is just a proposal, you can use whatever marker you want.
>>
>> 2.
>> You use a regex tool like SED together with the INPUT_FILTER option of 
>> doxygen to search for   /*%*/+linebreak   and remove it including the 
>> linebreak from the doxygen input. Note that this regular expression 
>> filtering does not change your source files.
>>
>> 3.
>> Doxygen should only see one big line.
>> That's it. Theoretically. It is just an idea, I have not tested.
> 
> Clemens, that's just a _neat_ idea.
> I wasn't aware of the INPUT_FILTER thing, never thinking I'd ever have 
> to preprocess my sources with anything other than cpp.
> 
> Do you know when INPUT_FILTER is applied?  Before or after cpp?
> 
> 
>> I have posted several messages this year, that deal about regular 
>> expressions and the usage of the SED tool together with doxygen.
>>
>> If you really want to dig into this, please let me hear whether it 
>> works. Good luck.
>>
>> Clemens
> I'll give this a try shortly.

I have successfully applied your suggestion, but using perl 
instead of sed (handling newlines in sed always freaks me a little).

Here's my prefilter.pl script:
------------------------------------------------------------

#!/usr/bin/perl

$/ = undef;
$_ = <>;
s%\s*//\n\s*\**\s*% %gs;
print;

------------------------------------------------------------
As you can see, I'm using a double slash "//" at the end of the 
line as continuation mark (because of the nice correspondence to 
poetry plus it shouldn't get in the way of anything else, being a 
comment-opener itself).

Any whitespace around this mark and any number of leading 
asterisks on the appended line is removed too.  In the example I 
gave in the original post, I can now write
       /**
        ** But see overloaded(int a, int b, int c, int d, int e, //
        ** int f, int g, int h, int i, int j, int k) for a more
        ** elaborate version. */
and get a link to the doc of the right method (tested).

So far, so good.  Thanks a lot, Clemens!

I will look to a more elaborate version of this in the next days. 
  Because this one has a flaw:  If ever I edit a doc comment 
containing such a long reference and it gets re-filled, I'll have 
the correct the placement of the continuation marks.

Maybe it would be best to join all lines in a paragraph without 
regard to a continuation mark.  This way, we wouldn't need it at all.

Got to ponder this a little.

Thanks again, and have fun
----Daniel

Re: [Doxygen-users] Linking to functions with long parameter lists

[Clemens F. <c....@os...>]

Hi again, Daniel.

Congratulations. This is very cool.

Generally I also prefer PERL.
The only reason for why I have choosen SED is that I deliver the SED 
binary and the doxygen binary together with my source code. A 
explicite installation of perl and/or doxygen is not required.

greetings
Clemens


On 16 Feb 2007 at 17:20, Daniel Rubin wrote:

> I have successfully applied your suggestion, but using perl 
> instead of sed (handling newlines in sed always freaks me a little).
> 
> Here's my prefilter.pl script:
> ------------------------------------------------------------
> 
> #!/usr/bin/perl
> 
> $/ = undef;
> $_ = <>;
> s%\s*//\n\s*\**\s*% %gs;
> print;
> 
> ------------------------------------------------------------
> As you can see, I'm using a double slash "//" at the end of the 
> line as continuation mark (because of the nice correspondence to
> poetry plus it shouldn't get in the way of anything else, being a
> comment-opener itself).
> 
> Any whitespace around this mark and any number of leading 
> asterisks on the appended line is removed too.  In the example I gave
> in the original post, I can now write
>        /**
>         ** But see overloaded(int a, int b, int c, int d, int e, // **
>         int f, int g, int h, int i, int j, int k) for a more **
>         elaborate version. */
> and get a link to the doc of the right method (tested).
> 
> So far, so good.  Thanks a lot, Clemens!
> 
> I will look to a more elaborate version of this in the next days. 
>   Because this one has a flaw:  If ever I edit a doc comment 
> containing such a long reference and it gets re-filled, I'll have the
> correct the placement of the continuation marks.
> 
> Maybe it would be best to join all lines in a paragraph without 
> regard to a continuation mark.  This way, we wouldn't need it at all.
> 
> Got to ponder this a little.
> 
> Thanks again, and have fun
> ----Daniel
> 

Re: [Doxygen-users] Linking to functions with long parameter lists

[Clemens F. <c....@os...>]

Regarding this regular expression trick to deal with linebreak formating in source code:

On 16 Feb 2007 at 11:24, Daniel Rubin wrote:

> Clemens, that's just a _neat_ idea.
> I wasn't aware of the INPUT_FILTER thing, never thinking I'd ever have
> to preprocess my sources with anything other than cpp.
> 
> Do you know when INPUT_FILTER is applied?  Before or after cpp?
> 

Hi Daniel!

I do not unterstand you question. Doxygen (and the input-filter) have 
nothing to do with running the compiler (cpp). The input-filter is 
applied before doxygen processes your files:

1.
Doxygen open a documented source file

2.
Doxygen applies the input filter which is an external program.

3.
Doxygen processes the output of the external program and makes the 
documentation.

4. 
Doxygen goes to the next file ... -> 1.

Clemens

Re: [Doxygen-users] Linking to functions with long parameter lists

[Daniel R. <dr...@ma...>]

Clemens Feige wrote:

> Regarding this regular expression trick to deal with linebreak formating in source code:
> 
> On 16 Feb 2007 at 11:24, Daniel Rubin wrote:
> 
>> Clemens, that's just a _neat_ idea.
>> I wasn't aware of the INPUT_FILTER thing, never thinking I'd ever have
>> to preprocess my sources with anything other than cpp.
>>
>> Do you know when INPUT_FILTER is applied?  Before or after cpp?
>>
> 
> Hi Daniel!
> 
> I do not unterstand you question. Doxygen (and the input-filter) have 
> nothing to do with running the compiler (cpp).

Sorry for the confusion.  By "cpp" I meant the C-preprocessor.  (I 
think "cpp" is its common name on Unixens.)


> The input-filter is 
> applied before doxygen processes your files:
> 
> 1.
> Doxygen open a documented source file
> 
> 2.
> Doxygen applies the input filter which is an external program.
> 
> 3.
> Doxygen processes the output of the external program and makes the 
> documentation.
> 
> 4. 
> Doxygen goes to the next file ... -> 1.

My question essentially was about which of steps 1. or 3. the 
C-preprocessor hooks in at.  But it might just be doxygen does the 
preprocessing stuff (macro expansion, including headers etc.) all 
by itself.  But when?  Most probably after applying the external 
filter -- anything doesn't seem sensible to me right now (so it 
would be at the beginning of step 3).

My intention was to find out what sort of line continuation symbol 
I could use.  I actually thought about using just the common 
backslash -- wondering if that might not be evaluated by the 
preprocessor before my filter had a chance to look at the code.
But I abandoned that idea, it leads to dangerous grounds that I am 
not willing to explore -- the backslash is just too laden with 
functionality already.

Anyway, I was able to solve my problem following your suggestion, 
see my other post.


Have fun
----Daniel

Re: [Doxygen-users] Linking to functions with long parameter lists

[Clemens F. <c....@os...>]

On 16 Feb 2007 at 16:58, Daniel Rubin wrote:

> > Regarding this regular expression trick to deal with linebreak
> > formating in source code:

> Sorry for the confusion.  By "cpp" I meant the C-preprocessor.  (I
> think "cpp" is its common name on Unixens.)

Hi Daniel.
You mean the C-preprocessor built in doxygen, don't you?
Ok, then the order is:

1.)
Doxygen opens a documented source file

2.)
Doxygen applies the input filter which is an external program.

3A)
Doxygen runs the doxygen-internal C-preprocessor (not the "real" 
preprocessor) over the the output of the external program. 
(If preprocesssing is enabled)

3B)
Doxygen does its work and makes the documentation.

4. 
Doxygen goes to the next file ... -> 1.

Clemens