Adding Doxygen tags to source with a perl script

[funda007]

Hi,

I am writing a script to convert my source code of old projects to doxygen format and then use doxygen to create documentation of those projects. So far i have converted my functions headers to doxygen with following commands

sed -i -e 's/^\*/ /g' *.c
sed -i -e 's/^\/\*[\*]*/\/\** /g' *.c
sed -i -e 's/\(FUNCTION\|DESCRIPTION\|INPUTS\|OUTPUTS\|DATA STRUCTURES\|FILE NAME\|COMPONENT\|FUNCTIONS\|DEPENDENCIES\)/\\par &/g' *.c

sed -i -e '1 s/*/&****/g' *.c
sed -i -e '/INPUTS/ a\ \\code' *.c
sed -i -e '/OUTPUTS/ i\ \\endcode' *.c
sed -i -e '/OUTPUTS/ a\ \\code' *.c
sed -i -e '/OUTPUTS/,/\*\// s/^ [\*]*\// \\endcode \n&/g' *.c

these commands convert my function header from


/************************************************** ***********************
*
* FUNCTION
*
* Factorial
*
* DESCRIPTION
*
* This Factorial function calculates the factorial of a number.
*
* INPUTS
*
* number number for which the factorial is to be calculated.
*
* OUTPUTS
*
* factorial value factorial of the input number.
* NVALID_PARM Invalid value of a parameter was
* passed in to the function.
*
************************************************** ***********************/

TO

/**

\par FUNCTION

DOT1X_Init

\par DESCRIPTION

This Factorial function calculates the factorial of a number.

\par INPUTS
\code

number number for which the factorial is to be calculated.

\endcode
\par OUTPUTS
\code

factorial value factorial of the input number.
INVALID_PARM Invalid value of a parameter was
passed in to the function.
\endcode
************************************************** **********************/


That is working fine for me. but the problem I am getting is that the doxygen is generating very dirty documentation for #define preprocessors used in my code. Doxygen generates a separate documentation for each #define i have used. For example.

doxygen will generate separate links and documentation for each of the following defines. that creates a mess.
#define ONE 1
#define TWO 2
#define THREE 3
#define FOUR 4
#define FIVE 5



The solution I thought about this problem is to group these macros together so that only one link and only one documentation will be generated for above macros. So i am looking for a perl script that will group continuous defines with a doxygen tag.

so the input file from
------------BOF---------

#define ONE 1
#define TWO 2
#define THREE 3
#define FOUR 4
#define FIVE 5


#define TRUE 1
#define FALSE 0

---------EOF---------


will be converted to

---------BOF----------

/*@{*/
#define ONE 1
#define TWO 2
#define THREE 3
#define FOUR 4
#define FIVE 5
/*@}*/

/*@{*/
#define TRUE 1
#define FALSE 0
/*@}*/

---------EOF--------

(note that each physical continuous defines are grouped with the tag separately.)

I tried writing sed and awk script for this purpose but found that sed and awk process one line at a time. then i went to do it with perl which can take a whole file as a single stream but i am facing problems doing this job. and i am also running out of time. can anyone help me in this regard? I know that will be a perl one liner for you people

Thanks,
Touseef

 

[feherke]

Hi

For [tt]perl[/tt] solution, please visit forum219 ( Perl ). This is a [tt]sed[/tt] solution, tested with GNU [tt]sed[/tt] :

/^#define/ { 
  x
  /#define/!i/*@{*/ 
  g
}

/^$/ {
  x
  /#define/i/*@}*/ 
  s/.*//
  g
}

Feherke.

http://rootshell.be/~feherke/

 

[feherke]

Hi

And an [tt]awk[/tt] solution, tested with [tt]gawk[/tt] and [tt]mawk[/tt] :

/^#define/ && !i { 
  print "/*@{*/"
  i=1
}

!/^#define/ && i { 
  print "/*@}*/"
  i=0
}

1

Feherke.

http://rootshell.be/~feherke/

 

[funda007]

Great Thanks feherke for your too quick solutions. Really you made my day.

Thanks again. I just tested it with one of my test file and it worked perfectly. I still have learn sed and awk properly before going to perl

Touseef

 

[feherke]

Hi

I tried writing sed and awk script for this purpose but found that sed and awk process one line at a time.

Just to clearify : [tt]awk[/tt] works with records, not with lines. The default record separator is the newline ( \n ) character, but you can change that to whatever is usefull for you. But for this you need [tt]gawk[/tt] or [tt]nawk[/tt].

For example to one or more empty lines :

BEGIN {
  RS="\n\n+"
}

/^#define/ {
  printf "/*@{*/\n" $0 "\n/*@}*/" RT
  next
}

{
  printf $0 RT
}

Or even to one or more consecutive #define lines :

BEGIN {
  RS="(#define[[:alnum:] ]+[[:cntrl:]])+"
}

1

RT~/#define/ {
  print "/*@{*/\n" RT "/*@}*/"
}

Auxiliar question to the gurus : how could I match the newline ( \n ) character in the above code. That [[:cntrl:]] is very ugly.

Feherke.

http://rootshell.be/~feherke/