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