Re: [Doxygen-develop] documenting c-struct members

[Michael D. <mi...@na...>]

On Friday 26 September 2003 20:46, Dimitri van Heesch wrote:
> On Fri, Sep 26, 2003 at 12:32:52PM +0200, Michael Daum wrote:
> > But I don't get exactly what I wanted. The c_struct is part of a group
> > (of related structures). The \var docu then goes into the group docu
> > (section Variables) and is marked 'inherited'. Actually I expected the
> > c_struct::field1 to be on the page documenting the c_struct.
>
> Me too. Are you sure only the c_struct is grouped? Or is the whole struct
> with everything in it grouped? This probably depends on whether @ingroup
> is used (good) or if the whole struct is in a @defgroup .. @{  ... @}
> block (bad in this case). Please provide an example to make it easier to
> discuss about the problem.

OK. 

Each headerfile is added to a group using @addtogroup. The implementations, which 
become part of that group aswell, are bundled into a c-file of the same
name. So I use @addtogroup for the c-file and the h-file. I think that's
what's intended to be done with those @addtogroups.

Here are three sniplets that (a) show how things work (b) how things don't
work as intended  and (c) how I'd like things to work.

(a) here's how things work right now, but which are inconvenient in terms
of code uglification.

/**
  @addtogroup MyGroup
  @{ 
*/

/**
  short descriptionof MyExportedTypeStruct.
  long description.
*/
typedef struct {
  int memberA; /**< lots of documentation here 
                             lots of documentation here 
                             lots of documentation here 
                             lots of documentation here 
                             lots of documentation here  */
  int memberB; /**< lots of documentation here
                             lots of documentation here 
                             lots of documentation here 
                             lots of documentation here 
                             lots of documentation here 
                             lots of documentation here 
                             lots of documentation here 
                             lots of documentation here 
                             lots of documentation here */
} MyExportedTypeStruct;
typedef MyExportedTypeStruct *MyExportedType; /**< type definition */

/** @} */

(b) here's how member documentation gets into the wrong place, that
is: onto the MyGroup page but not on the MyExportedTypeStruct page.

/**
  @addtogroup MyGroup
  @{ 
*/

/**
  short descriptionof MyExportedTypeStruct.
  long description.
*/
typedef struct {
  int memberA;
  int memberB;
} MyExportedTypeStruct;
typedef MyExportedTypeStruct *MyExportedType; /**< type definition */

/** \var MyExportedTypeStruct::memberA
        lots of documentation here 
        lots of documentation here 
        lots of documentation here 
        lots of documentation here 
        lots of documentation here
*//** \var MyExportedTypeStruct::memberB
        lots of documentation here 
        lots of documentation here 
        lots of documentation here 
        lots of documentation here 
        lots of documentation here
*/

/** @} */

(c) And here's how I'd like to document things:

/**
  @addtogroup MyGroup
  @{ 
*/

/**
  short descriptionof MyExportedTypeStruct.
  long description.
  \var memberA
        lots of documentation here 
        lots of documentation here 
        lots of documentation here 
        lots of documentation here 
        lots of documentation here
  \var memberB
        lots of documentation here 
        lots of documentation here 
        lots of documentation here 
        lots of documentation here 
        lots of documentation here
*/
typedef struct {
  int memberA;
  int memberB;
} MyExportedTypeStruct;
typedef MyExportedTypeStruct *MyExportedType; /**< type definition */

/** @} */


	Micha.

-- 
-- Michael Daum
-- Natural Language Systems
-- Faculty of Informatics
---University of Hamburg
-- http://nats-www.informatik.uni-hamburg.de/~micha