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

[Dimitri v. H. <di...@st...>]

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