[Doxygen-users] [Large] Algorithmics comments or comments inside body functions.

[Jose L. Z. <jlz...@ca...>]

Hi all

I come back again about the idea of ** what ** do a function or ** how ** do 
the function his work. I believe is important the documentation show two 
things.

Doxigen is wonderful but not scan inside the function and I believe that 
inside the function must be the comments that say ** how ** the function work.

But Doxigen is wonderful and can filtering the files before processing. OK. I 
writed a dirty perl script filter to scan and extract the comments and put in 
special comment nearest. One example.

# This dirty perl script extract "Algorithmic comments" from the function's 
# body and they are put inside
# nearest special comment /** ... */
#
# A algorithmic comment has the format :
#
#           // <(.*)> Algorithmic comment.
#           // comment continuation.
#              until a no init comment line.
#
# Where (.*) can to be :
#
#    <>   : Algorithmic comment init.
#    <+>  : Algorithmic comment init indent +1 position.
#    <->  : Algorithmic comment init indent -1 position.
#    <-n> : Algorithmic comment init indent -n position.
#
# EXAMPLE :
#
#   /**
#    This is a little file example
#   */
#
#   /**
#    * @brief : This function do something
#    *
#    * You can put in this place some comment.
#    *
#    */
#   void funcion(void)
#   {
#       int i;
#
#   // <> Increment the global variable a
#
#       a++;
#
#   // <> Printing the message
#   // the message is "Sayonara baby"
#
#       PrintMessage("Sayonara baby");
#
#   // It can be normal comments
#
#   // <> For all componets in the array
#       for(i=0;i<a;i++)
#       { // <+>
#           // <> print the component message
#           ArrayComponet[i].PrintMessage();
#
#           // <> For all component lines
#           while(ArrayComponent[i].NumLines())
#           { // <+>
#               // <> Get the line
#               CLine a=ArrayComponent[i].GetLine()
#               // <> Printing
#               a.Print();
#               // <> Deleting
#               a.Delete();
#           } // <->
#       }// <->
#
#   // <> Deleting the Array
#   ArrayComponent.Delete();
#
#   }
#
# THE OUTPUT
#
#   /**
#    This is a little file example
#   */
#
#   /**
#    * @brief : This function do something
#    *
#    * You can put in this place some comment.
#<H3>Algorithm</H3>
#<UL>
#  <LI> Increment the global variable a
#  <LI> Printing the message
#       the message is "Sayonara baby"
#  <LI> For all componets in the array
#  <UL>
#     <LI> print the component message
#     <LI> For all component lines
#     <UL>
#        <LI> Get the line
#        <LI> Printing
#        <LI> Deleting
#     </UL>
#  </UL>
#  <LI> Deleting the Array
#</UL>
#    */
#   void funcion(void)
#   {
#       int i;
#
#
#       a++;
#
#
#       PrintMessage("Sayonara baby");
#
#   // It can be normal comments
#
#       for(i=0;i<a;i++)
#       {
#           ArrayComponet[i].PrintMessage();
#           while(ArrayComponent[i].NumLines())
#           {
#               CLine a=ArrayComponent[i].GetLine()
#               a.Print();
#               a.Delete();
#           }
#       }
#
#   ArrayComponent.Delete();
#   }
#

This is enough for my but It should be wonderful that Doxigen be able scan 
inside body functions and it be able recognize special comments before 
keywords (for, if, while ...) and indent automaticaly inside the keywords 
body or a algorithm graphic about ** how ** the function work.

It is only a idea.

Bye

P.D. I can send to you the script or put it in some ftp server but it is very 
simple.
-- 
José Luis Zabalza
jlz...@ca...
Linux User 172551