RE: [Doxygen-users] Documenting IDL

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

> -----Original Message-----
> From: dox...@li...
> [mailto:dox...@li...]On Behalf Of Dale
> Ogilvie
> Sent: 08 May 2001 06:27
> To: 'dox...@li...'
> Subject: [Doxygen-users] Documenting IDL
>
>
> Hi,
>
> Does anyone know how to get an identifier to be an alias for another
> identifier in doxygen? Basically, I want two identifiers "IRecord" and
> "IRecordPtr" both to index the same documented COM interface.
>
<snip>
>
> All good, but we also use microsoft smart pointer wrappers for our
> interfaces. These wrapper classes can be treated exactly like
> the interfaces
> they wrap, and they have a number of advantages which mean
> that we tend to
> use them almost exclusively. Instead of writing raw code like:
>
> IRecord* pRecord = NULL;
> ...
> pRecord->Doit();
>
> We tend to use the smart pointer wrappers and write:
>
> IRecordPtr pRecord;
> ...
> pRecord->Doit();
>
> Now to our problem. If we press F1 on IRecordPtr we want the
> help to jump to
> the IRecord topic!
>
> Does anyone know how to get doxygen to treat IRecordPtr as an
> alias for
> IRecord???
>
> thanks
>
> Dale
>

That is a very good question - if I can broaden it out, doesn't it apply to any
class that defines operator->() ? This covers a whole raft of coding idioms that
includes a variety of "smart pointers", which I use a lot in my code.

Perhaps if Doxygen could recognise that operator, note what type it is returning
and generate a reference to the returned type...not really sure how it would
work...


There is a problem though - many "smart-pointer" classes also declare their own
methods: quick example, I have a ref counting pointer that declares IsValid() to
check for whatever-the-condition-is-that-corresponds-to-a-non-null-pointer:

 ThingPtr fred;
 ..blah..
 if (fred.IsValid())
    fred->DoSomething();

[I have less trivial methods on some pseudo-pointer classes as well]

So if you convert from ThingPtr to Thing every time there is the risk of the
documentation's reader missing out on the other methods of ThingPtr.

Regards,
Stephen Goudge