doxygen-users

Re: [Doxygen-users] Typedef Aliases Don't Work

[Scott P. <sco...@ho...>]

I appreciate that sometimes you want the hotlinks to go to the typedef.  =
But I am specifically using typedefs to hide the true name of some =
structs.  I don't want my docs cluttered with the struct name since that =
is not what the programmers will ever use in their code.

A configuration option of some sort would work for me.

What I really want is a specific ALIAS option so that I could completely =
replace the actual struct name from ALL docs (even the doc page for the =
struct) and have my typedef name be the only thing that ever appears in =
the docs.

I have a header file that keeps a typedef defined as the 'latest =
version' of a struct that may evolve.  The older legacy structs will =
still be available in the header but they will be undocumented.

e.g.

struct Data1
{
  int x;
};

// latest version of 'Data'
struct Data2
{
 int x;
 int addedMember; // new feature needs new data
};

typedef Data2 Data;

So recompiling withthe latest headers will always use the latest structs =
without changing the source.

Scott

  ----- Original Message -----=20
  From: Trevor Robinson=20
  To: 'dox...@li...'=20
  Sent: Thursday, June 07, 2001 5:22 PM
  Subject: RE: [Doxygen-users] Typedef Aliases Don't Work


  I didn't know what the documentation said, but I have seen the =
behavior you describe.  However, I think it's good that Doxygen links to =
the typedef because sometimes you need to see the typedef.  For example, =
take typedefs of template instantiations.  Assuming you have "typedef =
things<stuff> junk", if clicking on "junk" just took you to "template =
<class T> things", you wouldn't know "stuff" was involved.  Given the =
necessity of linking to the typedef here, and the desire for =
consistency, it seems like the correct fix is to change the =
documentation.

  Personally, I also like linking to the typedef so I know where the =
typedef is defined, perhaps to know what header to #include.  It would =
be confusing to click on "junk" and have the definition for "stuff" =
appear.  Also, since Doxygen let's you document typedefs, it seems =
consistent to treat them like first-class entities when linking, even =
though the compiler just treats them like aliases.

  That said, maybe this is one of those cases that deserves a =
configuration option.

  -Trevor

    -----Original Message-----
    From: Scott Palmer [mailto:sco...@ho...]
    Sent: Thursday, June 07, 2001 3:56 PM
    To: dox...@li...
    Subject: [Doxygen-users] Typedef Aliases Don't Work


    The documentation for doxygen clearly states:

    "Typedefs that involve classes, structs and unions, like
    typedef struct StructName TypeName
    create an alias for StructName, so links will be generated to =
StructName,  when either StructName itself or TypeName is encountered."


    However this is NOT true.  The example HTML documentation does not =
even do this.  Clicking on the name of the typedef in the example =
documenation in the online help brings you to documentation for the =
typedef itself NOT the associated struct.

    This problem seems to have been around since at least 1.2.6, and is =
still present in 1.2.8.

    Are there any workarounds?  Is this a known problem?

    Thanks,

    Scott



    ---
    Outgoing mail is certified Virus Free.
    Checked by AVG anti-virus system (http://www.grisoft.com).
    Version: 6.0.255 / Virus Database: 128 - Release Date: 2001-05-17

RE: [Doxygen-users] Typedef Aliases Don't Work

[Stephen G. <ste...@cl...>]

Couldn't you get the same result in your code by dropping the typedef
completely, leaving the latest version of the struct with the name 'Data' and,
when a new field is added, copying the existing 'struct Data', naming the copy
'struct Data<insert version number here>' and finally adding the new field to
'Data'?

Then Doxygen will work fine as-is, your code will work fine with only a couple
of changes in the header. The only difference would be that, at the moment, you
can refer to the latest version by two different names, so if you make use of
that fact then ignore this suggestion.

Regards,
Stephen Goudge


-----Original Message-----
From: dox...@li...
[mailto:dox...@li...]On Behalf Of Scott Palmer
Sent: 08 June 2001 02:43
To: dox...@li...
Subject: Re: [Doxygen-users] Typedef Aliases Don't Work

<snip>

I have a header file that keeps a typedef defined as the 'latest version' of a
struct that may evolve.  The older legacy structs will still be available in the
header but they will be undocumented.

e.g.

struct Data1
{
  int x;
};

// latest version of 'Data'
struct Data2
{
 int x;
 int addedMember; // new feature needs new data
};

typedef Data2 Data;

So recompiling withthe latest headers will always use the latest structs without
changing the source.

Scott

Re: [Doxygen-users] Typedef Aliases Don't Work

[Scott P. <sco...@ho...>]

No, he prototypes of the functions that take the struct as an argument =
would get messed up.  The functions are also numbered in a similar way.

void Blah1(Data *pStuff);
#define Blah Blah1

is really:

void Blah1(Data1 *pStuff);

because of the typedef.

When Data2 is created I change that prototype to specifically have the # =
suffix and add a new prototype for Blah2)

void Blah2(Data *pStuff2);

Scott


  ----- Original Message -----=20
  From: Stephen Goudge=20
  To: dox...@li...=20
  Sent: Friday, June 08, 2001 6:25 AM
  Subject: RE: [Doxygen-users] Typedef Aliases Don't Work


  Couldn't you get the same result in your code by dropping the typedef
  completely, leaving the latest version of the struct with the name =
'Data' and,
  when a new field is added, copying the existing 'struct Data', naming =
the copy
  'struct Data<insert version number here>' and finally adding the new =
field to
  'Data'?

  Then Doxygen will work fine as-is, your code will work fine with only =
a couple
  of changes in the header. The only difference would be that, at the =
moment, you
  can refer to the latest version by two different names, so if you make =
use of
  that fact then ignore this suggestion.

  Regards,
  Stephen Goudge


  -----Original Message-----
  From: dox...@li...
  [mailto:dox...@li...]On Behalf Of Scott =
Palmer
  Sent: 08 June 2001 02:43
  To: dox...@li...
  Subject: Re: [Doxygen-users] Typedef Aliases Don't Work

  <snip>

  I have a header file that keeps a typedef defined as the 'latest =
version' of a
  struct that may evolve.  The older legacy structs will still be =
available in the
  header but they will be undocumented.

  e.g.

  struct Data1
  {
    int x;
  };

  // latest version of 'Data'
  struct Data2
  {
   int x;
   int addedMember; // new feature needs new data
  };

  typedef Data2 Data;

  So recompiling withthe latest headers will always use the latest =
structs without
  changing the source.

  Scott



  _______________________________________________
  Doxygen-users mailing list
  Dox...@li...
  http://lists.sourceforge.net/lists/listinfo/doxygen-users


  ---
  Outgoing mail is certified Virus Free.
  Checked by AVG anti-virus system (http://www.grisoft.com).
  Version: 6.0.255 / Virus Database: 128 - Release Date: 2001-05-17