Re: [Doxygen-users] Using a tag file to document just a C++ member function

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Hi Dimitri,

Thank you for writing back.

Here is an example.

Consider the following file organization:

src/include/module.h
src/module/code.cpp
src/module/code2.cpp

The global header file, module.h, is built by a program using directives
placed in the source files: module/code.cpp and module/code2.cpp.

module.h is the exported API. I want to fully document this, meaning
all methods including arguments to the methods.

Consider the following tivial code.cpp file:

-------------------------------------------------------------------
 BEGIN_EXPORT
 /**@brief Square class
  */
 class EXPORT_CLASS Square {
     public:
         void Square(int);
         /**@brief Default constructor
          */
         void Square() { side = 0; }
         int Area();
     private:
        int side;  /**<@brief Length of the side. */
 };
 END_EXPORT

 /**@brief Constructor
  */
 void Square::Square(
     int n  /**< Length of the side. */
     )
 {
     side = n;
 }

 /**@brief Computes the area of the square.
  *
  * @return The area.
  */
 int Square::Area(
     )
 {
     return side * side;
 }
-------------------------------------------------------------------

Running the 'makeheader' program across the module directories
produces a module.h file that looks like:
-------------------------------------------------------------------
...
 /**@brief Square class
  */
 class IMPORT_CLASS Square {
     public:
         void Square(int);
         /**@brief Default constructor
          */
         void Square() { side = 0; }
         int Area();
     private:
        int side;  /**<@brief Length of the side. */
 };
...
-------------------------------------------------------------------

Note that BEGIN_EXPORT, END_EXPORT, EXPORT_CLASS, IMPORT_CLASS are
our macros and get either removed or changed by the 'makeheader'
program.

Now I have chosen most of the time to put all the documentation
for the method with the definition including the method
parameters. This works fine when you use Doxygen to document the
whole module directory.

Now I want to Doxygen just the generated header file, module.h. That is
what we want to publish for other users. It needs to have all
the documentation about method arguments, etc.

How do we do this? Now you would say, you have to put all the
documentation in the class definition. I see two drawbacks:

1. For large classes, the class definition becomes unreadable at the
   source level with all that information.
2. The information about the method is not close to the implementation.
   I think it helps the implementor to have that information close to
   where the work is done.

Doxygen has all the information after running it across the module
directory. The generated header file is just a subset view of the
same information, but with some pieces missing. I want to use the
tag file to fill out those missing pieces of information.

So I thought that I could generate a tag file for the module directory
first and then use it to 'complete' the documentation for the two
methods, Square() and Area() when I Doxygen just the generated
header file, module.h.

I was unsuccessful. The tag file appears to have no affect.
Did I do something wrong?

The example in your documentation shows only a whole class
coming from the tag file, not a piece like a couple of methods
in the example above.

This is what I mean, "I want Doxygen to try to extract pieces of
a class, not just a whole class from a tag file".

Is this clearer?

Sincerely,
Martin Knapp-Cordes

---------------------------------------------------------------
|  Martin Knapp-Cordes               ma...@ma...     |
|  The MathWorks, Inc.               http://www.mathworks.com |
|  3 Apple Hill Drive                Natick, MA  01760        |
|  Tel: (508) 647-7321               Fax: (508) 647-7015      |
---------------------------------------------------------------

On Tue, 14 Feb 2006, Dimitri van Heesch wrote:

> I don't understand what you are try to do. Perhaps an example will
> help.
>
> Regards,
>   Dimitri
>
> On 2/3/06, Martin Knapp-Cordes <ma...@ma...> wrote:
> >
> > Hello,
> >
> > Question: Can one use a tag file to get the documentation for
> >           just a member function of a C++ class?
> >
> > Here is the situation. Output is HTML. Version is 1.4.5.
> >
> > We autogenerate our C++ headers from the source including
> > exported headers across 'modules'. The exported headers are
> > our published APIs. I would like to document our member
> > functions including parameters with the member definition,
> > not in the class declaration. So the Doxygen comments for
> > the member functions are not currently in the autogenerated
> > exported header.  Currently, I have fully documented only a
> > part of the 'module'.  I have generated a tag file for that
> > piece which includes complete documentation for all member
> > functions for this part.  Now I want to just run Doxygen on
> > just the exported header separately.  Doxygen appears to
> > find the tag file.  There are no tag reading errors in the
> > diagnostic output. It definitely finds the file, because I
> > was getting an error until I fixed things. But there is no
> > documentation for those member functions. The links are dark.
> > The Doxygen comments that get put in the exported header
> > appear to produce the right output.  The exported header
> > starts with a \file comment.
> >
> > Am I doing something wrong or is this capability simply
> > not supported?
> >
> > If you need more information please let me know.
> >
> > Sincerely,
> > Martin Knapp-Cordes
> >
> > ---------------------------------------------------------------
> > |  Martin Knapp-Cordes               ma...@ma...     |
> > |  The MathWorks, Inc.               http://www.mathworks.com |
> > |  3 Apple Hill Drive                Natick, MA  01760        |
> > |  Tel: (508) 647-7321               Fax: (508) 647-7015      |
> > ---------------------------------------------------------------
> >
> >
> >
> > -------------------------------------------------------
> > This SF.net email is sponsored by: Splunk Inc. Do you grep through log
> > files
> > for problems?  Stop!  Download the new AJAX search engine that makes
> > searching your log files as easy as surfing the  web.  DOWNLOAD SPLUNK!
> > http://sel.as-us.falkag.net/sel?cmd=lnk&kid=103432&bid=230486&dat=121642
> > _______________________________________________
> > Doxygen-users mailing list
> > Dox...@li...
> > https://lists.sourceforge.net/lists/listinfo/doxygen-users
> >
>