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

[Martin Knapp-C. <ma...@ma...>]

Hi Dimitri,

Great suggestion! I tried it out and it works great. As you
pointed out the function/method signature and argument names
get duplicated. But I look at it as a form of self-check. Also, this
style only applies to exported items.

I appreciate your help.

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 Thu, 16 Feb 2006, Dimitri van Heesch wrote:

> On Thu, Feb 16, 2006 at 02:52:44PM -0500, Martin Knapp-Cordes wrote:
> > 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?
>
> Yes, I think what could do is using the @fn command in combination
> with your macros, i.e.:
>
> BEGIN_EXPORT
> /** @fn Square::Square(int n)
>  *  @brief Constructor
>  *  @param n Length of the side.
>  */
> END_EXPORT
> void Square::Square(int n)
> {
> }
>
> It causes some duplication of information and you can't document
> parameters inline, but it keeps the documentation close to the
> definition.
>
> If your output is only classes and their methods you can also
> just document these like you did, set EXTRACT_ALL and SOURCE_BROWSER to NO and
> pass all input files to doxygen. Doxygen will generate a document with just the
> classes and leave output the implementation stuff that should not be part of
> the API.
>
> Tag files are for another purpose, i.e. to link one project to another.
>
> I hope this helps.
>
> Regards,
>   Dimitri
>
>