doxygen-users

[Doxygen-users] Documenting IDL

[Dale O. <Dal...@tr...>]

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.

We are using doxygen to document our Microsoft IDL. This produces wonderful
documentation for our COM interfaces, and we have integrated the resulting
compiled HTML into our MS Visual studio help so that when we press F1 on one
of our interface definitions we see the docs for our interface!

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

[Doxygen-users] Documenting IDL

[Francois St-A. <fst...@do...>]

I am in the process of documenting an IDL file using Doxygen.

Are there any examples available out there that could help me in my =
task?
I'm looking tips on documenting an IDL file using JavaDoc-style =
comments as
opposed to a Java file in straight JavaDoc.

I'm also looking to better control the HTML output: how do I get text =
to
appear int the "main page" section? how can I get rid of sections =
(namespace
list, alphabetical list, compound list, etc.? I'm asking because, in my =
IDL,
there is only one interface that I want to document and I think that =
the
different would confuse a reader more than anything.

Fran=E7ois St-Arnaud (Eng.), Senior Software Developer
585 Charest Blvd E., 7th Floor, Quebec, QC, Canada, G1K 3J2
Tel: 418 681-8022/0006 x243  Fax: 681-8015

Visit our new website and see the benefits of our
PowerBus(tm) Technology @  www.domosys.com=20

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

RE: [Doxygen-users] Documenting IDL

[Victor A. W. Jr. <va...@ru...>]

Slightly off topic (maybe this is C++ style):
Is there some reason you chose to write IsValid() rather than overloading a 
conversion to void*:

operator void*() {return static_cast<void*>(IsValid());}
would suffice.

Then you could write (like the 'real pointer' you're emulating:
ThingPtr fred;
.
.
.
if (fred)
    fred->DoSomething();

similarly for operator !()
so you can write:
if (!fred)
    blah....blah...
At Tuesday 2001/05/08 04:02, you wrote:
> > -----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
>[deleted]
>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
>
>
>_______________________________________________
>Doxygen-users mailing list
>Dox...@li...
>http://lists.sourceforge.net/lists/listinfo/doxygen-users

Victor A. Wagner, Jr.
PGP RSA fingerprint = 4D20 EBF6 0101 B069 3817 8DBF C846 E47A
PGP D-H fingerprint = 98BC 65E3 1A19 43EC 3908 65B9 F755 E6F4 63BB 9D93
The five most dangerous words in the English language:
               "There oughta be a law"

(off-topic) RE: [Doxygen-users] Documenting IDL

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

> From: dox...@li...
> [mailto:dox...@li...]On Behalf
> Of Victor A.
> Wagner, Jr.
> Sent: 08 May 2001 12:17
> To: dox...@li...
> Subject: RE: [Doxygen-users] Documenting IDL
>
>
> Slightly off topic (maybe this is C++ style):
> Is there some reason you chose to write IsValid() rather than
> overloading a
> conversion to void*:
>
> operator void*() {return static_cast<void*>(IsValid());}
> would suffice.
>
> Then you could write (like the 'real pointer' you're emulating:
> ThingPtr fred;
> .
> .
> .
> if (fred)
>     fred->DoSomething();
>
> similarly for operator !()
> so you can write:
> if (!fred)
>     blah....blah...
> At Tuesday 2001/05/08 04:02, you wrote:
> > > -----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
> >[deleted]
> >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.
> >

Ah, the number of problems trying to do that caused me :-(

I did originally have an operator int() that could be used in if-statements,
which worked fine using VC++2 through to VC++4; then a client bought VC++5 and
it became ambiguous (I forget the precise reason why), so everything switched to
IsValid() from then on.

I would be tempted nowadays to try and hid IsValid(), but I take the attitude
that if something was done because one compiler needed it (and the results are
still legal) then keep it in, because the code will be used on a.n.other
compiler next week, or the week after...

Even with a decent compiler, there is the vexed question of what the cast
operator should be casting _to_ - you don't really want to return another
pointer type, as that looks too much like you're providing a backdoor. These
days, 'bool' would be a reasonable choice (now that the compilers actually
support 'bool'). The best choice would be the mythical 'logical' type that 'if',
'while' etc use, but that isn't available :-(

Stephen Goudge

Re: (off-topic) RE: [Doxygen-users] Documenting IDL

[Hendrik S. <Do...@HS...>]

"Stephen Goudge" <ste...@pi...> wrote:

> [...]
> I did originally have an operator int() that could be used in if-statements,
> which worked fine using VC++2 through to VC++4; then a client bought VC++5 and
> it became ambiguous (I forget the precise reason why), so everything switched to
> IsValid() from then on.

  'int' seems like one of the most troublesome ideas. 
  (What's 'spa+spb' to become then?) 

> [...]
> Even with a decent compiler, there is the vexed question of what the cast
> operator should be casting _to_ - you don't really want to return another
> pointer type, as that looks too much like you're providing a backdoor. These
> days, 'bool' would be a reasonable choice (now that the compilers actually
> support 'bool'). The best choice would be the mythical 'logical' type that 'if',
> 'while' etc use, but that isn't available :-(

  Oh, but that's available: It's named 'bool'. 
  But 'bool' isn't all that good either, because it's an 
  arithmetic type. (Or was it convertible into one?) 
  You could thus write 'sp+5' and get funny results. 

  In his book "Modern C++ Design" Andrei Alexandrescu 
  discusses this issue. His idea (typing from memory): 

  template<class T>
  class SmartPtr {
    private: 
      class Tester {
        void operator delete(void*);
      };
    public: 
      operator Tester*() const 
      {
        if( !IsValid() ) 
          return NULL;
        static Tester tester;
        return tester;
      }
      // ... 
  };

  (The private 'operator delete()' is there to prevent 
  users from trying to delete the result of calling the 
  convertion operator.) 

  I have not used this yet, so I don't know whether it's 
  really as great an idea as it seemed to me. 

> Stephen Goudge

  Schobi

RE: (off-topic) RE: [Doxygen-users] Documenting IDL

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

> -----Original Message-----
> From: dox...@li...
> [mailto:dox...@li...]On Behalf Of Hendrik
> Schober
> Sent: 10 June 2001 20:58
> To: dox...@li...
> Subject: Re: (off-topic) RE: [Doxygen-users] Documenting IDL
>
>
> "Stephen Goudge" <ste...@pi...> wrote:
>
> > [...]
> > I did originally have an operator int() that could be used
> in if-statements,
> > which worked fine using VC++2 through to VC++4; then a
> client bought VC++5 and
> > it became ambiguous (I forget the precise reason why), so
> everything switched to
> > IsValid() from then on.
>
>   'int' seems like one of the most troublesome ideas.
>   (What's 'spa+spb' to become then?)
>
> > [...]
> > Even with a decent compiler, there is the vexed question of
> what the cast
> > operator should be casting _to_ - you don't really want to
> return another
> > pointer type, as that looks too much like you're providing
> a backdoor. These
> > days, 'bool' would be a reasonable choice (now that the
> compilers actually
> > support 'bool'). The best choice would be the mythical
> 'logical' type that 'if',
> > 'while' etc use, but that isn't available :-(
>
>   Oh, but that's available: It's named 'bool'.

The "the mythical 'logical' type that 'if', 'while' etc use" is not 'bool' - I
suppose you could produce a parser that used bool there, but just taking a straw
poll around the office, the guy sitting next to me (working on a C compiler)
uses 'long int' for 'if' etc, which is what the Standard says you do (hence the
use of operator int() to feed 'if' in the oldest code). Meanwhile, in my
program, a C-expression evaluator has a type 'logical' that is only used
internally (ie, from the point of view of someone writing an expression to be
evaluated, is mythical because you can not declare anything to have type
'logical') and lives at the very opposite end of the automatic type promotion
ladder from 'bool'.

Also, unfortunately, all that time ago, 'bool' was not available in all the
compilers being used :-(

>   But 'bool' isn't all that good either, because it's an
>   arithmetic type. (Or was it convertible into one?)
>   You could thus write 'sp+5' and get funny results.

<snip>

That points out the problem exactly - all of the types that you can use here
already have well-known meanings and tend to imply that it is possible to use
them in expressions _other_ than just 'if'. No matter what you choose, you can
write something that will give funny results.

Hence (not to be taken too seriously) wish to be able to use a type, 'logical',
that does not carry any such baggage, based on the fact that I _know_ such a
type does/can live deep within the bowels of a compiler.

The _only_ answer I know of that is possible to implement _and_ totally free of
any such baggage is an "IsValid()" method - which is right back to where we
started.

>   In his book "Modern C++ Design" Andrei Alexandrescu
>   discusses this issue. His idea (typing from memory):
>
>   template<class T>
>   class SmartPtr {
>     private:
>       class Tester {
>         void operator delete(void*);
>       };
>     public:
>       operator Tester*() const
>       {
>         if( !IsValid() )
>           return NULL;
>         static Tester tester;
>         return tester;
>       }
>       // ...
>   };
>
>   (The private 'operator delete()' is there to prevent
>   users from trying to delete the result of calling the
>   convertion operator.)
>
>   I have not used this yet, so I don't know whether it's
>   really as great an idea as it seemed to me.
>
> > Stephen Goudge
>
>   Schobi

Aha, yet another approach :-)

The suggestions - _all_ of them - all have their merits and all can all work
extremely well, but, just like the search the One True String Class, there is no
absolute best answer to this. Shame really.

Now, back to Doxygen...

Stephen Goudge

RE: (off-topic) RE: [Doxygen-users] Documenting IDL

[Victor A. W. Jr. <va...@ru...>]

or use void* like I ORIGINALLY suggested (and is suggested by looking at 
how the STL does it with iterators.

At Monday 2001/06/11 09:37, you wrote:

> > -----Original Message-----
> > From: dox...@li...
> > [mailto:dox...@li...]On Behalf Of Hendrik
> > Schober
> > Sent: 10 June 2001 20:58
> > To: dox...@li...
> > Subject: Re: (off-topic) RE: [Doxygen-users] Documenting IDL
> >
> >
> > "Stephen Goudge" <ste...@pi...> wrote:
> >
> > > [...]
> > > I did originally have an operator int() that could be used
> > in if-statements,
> > > which worked fine using VC++2 through to VC++4; then a
> > client bought VC++5 and
> > > it became ambiguous (I forget the precise reason why), so
> > everything switched to
> > > IsValid() from then on.
> >
> >   'int' seems like one of the most troublesome ideas.
> >   (What's 'spa+spb' to become then?)
> >
> > > [...]
> > > Even with a decent compiler, there is the vexed question of
> > what the cast
> > > operator should be casting _to_ - you don't really want to
> > return another
> > > pointer type, as that looks too much like you're providing
> > a backdoor. These
> > > days, 'bool' would be a reasonable choice (now that the
> > compilers actually
> > > support 'bool'). The best choice would be the mythical
> > 'logical' type that 'if',
> > > 'while' etc use, but that isn't available :-(
> >
> >   Oh, but that's available: It's named 'bool'.
>
>The "the mythical 'logical' type that 'if', 'while' etc use" is not 'bool' - I
>suppose you could produce a parser that used bool there, but just taking a 
>straw
>poll around the office, the guy sitting next to me (working on a C compiler)
>uses 'long int' for 'if' etc, which is what the Standard says you do 
>(hence the
>use of operator int() to feed 'if' in the oldest code). Meanwhile, in my
>program, a C-expression evaluator has a type 'logical' that is only used
>internally (ie, from the point of view of someone writing an expression to be
>evaluated, is mythical because you can not declare anything to have type
>'logical') and lives at the very opposite end of the automatic type promotion
>ladder from 'bool'.
>
>Also, unfortunately, all that time ago, 'bool' was not available in all the
>compilers being used :-(
>
> >   But 'bool' isn't all that good either, because it's an
> >   arithmetic type. (Or was it convertible into one?)
> >   You could thus write 'sp+5' and get funny results.
>
><snip>
>
>That points out the problem exactly - all of the types that you can use here
>already have well-known meanings and tend to imply that it is possible to use
>them in expressions _other_ than just 'if'. No matter what you choose, you can
>write something that will give funny results.
>
>Hence (not to be taken too seriously) wish to be able to use a type, 
>'logical',
>that does not carry any such baggage, based on the fact that I _know_ such a
>type does/can live deep within the bowels of a compiler.
>
>The _only_ answer I know of that is possible to implement _and_ totally 
>free of
>any such baggage is an "IsValid()" method - which is right back to where we
>started.
>
> >   In his book "Modern C++ Design" Andrei Alexandrescu
> >   discusses this issue. His idea (typing from memory):
> >
> >   template<class T>
> >   class SmartPtr {
> >     private:
> >       class Tester {
> >         void operator delete(void*);
> >       };
> >     public:
> >       operator Tester*() const
> >       {
> >         if( !IsValid() )
> >           return NULL;
> >         static Tester tester;
> >         return tester;
> >       }
> >       // ...
> >   };
> >
> >   (The private 'operator delete()' is there to prevent
> >   users from trying to delete the result of calling the
> >   convertion operator.)
> >
> >   I have not used this yet, so I don't know whether it's
> >   really as great an idea as it seemed to me.
> >
> > > Stephen Goudge
> >
> >   Schobi
>
>Aha, yet another approach :-)
>
>The suggestions - _all_ of them - all have their merits and all can all work
>extremely well, but, just like the search the One True String Class, there 
>is no
>absolute best answer to this. Shame really.
>
>Now, back to Doxygen...
>
>Stephen Goudge
>
>
>
>_______________________________________________
>Doxygen-users mailing list
>Dox...@li...
>http://lists.sourceforge.net/lists/listinfo/doxygen-users

Victor A. Wagner, Jr.
PGP RSA fingerprint = 4D20 EBF6 0101 B069 3817 8DBF C846 E47A
PGP D-H fingerprint = 98BC 65E3 1A19 43EC 3908 65B9 F755 E6F4 63BB 9D93
The five most dangerous words in the English language:
               "There oughta be a law"

RE: (off-topic) RE: [Doxygen-users] Documenting IDL

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

> -----Original Message-----
> From: dox...@li...
> [mailto:dox...@li...]On Behalf 
> Of Victor A.
> Wagner, Jr.
> Sent: 11 June 2001 13:18
> To: dox...@li...
> Subject: RE: (off-topic) RE: [Doxygen-users] Documenting IDL
> 
> 
> or use void* like I ORIGINALLY suggested (and is suggested by 
> looking at 
> how the STL does it with iterators.
> 

Which is one of the items that was covered by the last sentence:

> >
> >The suggestions - _all_ of them - all have their merits and 
> all can all work
> >extremely well...
> 

You pays your money and takes your choice.

Re: (off-topic) RE: [Doxygen-users] Documenting IDL

[Hendrik S. <Do...@HS...>]

"Victor A. Wagner, Jr." <va...@ru...> wrote:

> or use void* like I ORIGINALLY suggested (and is suggested by looking at 
> how the STL does it with iterators.

  It's easy to confuse this with a pointer to the object 
  taken care of by the smart pointer. 

> [...] 
> >The "the mythical 'logical' type that 'if', 'while' etc use" is not 'bool' - I
> >suppose you could produce a parser that used bool there, but just taking a 
> >straw
> >poll around the office, the guy sitting next to me (working on a C compiler)
> >uses 'long int' for 'if' etc, which is what the Standard says you do 
> >(hence the
> >use of operator int() to feed 'if' in the oldest code). Meanwhile, in my
> [...]

  I'm not so sure about that. But I always thought, since 
  the standard it's 'bool' for C++. (The guy next to you 
  is working on a C compiler, after all. ;^> )

> > >   template<class T>
> > >   class SmartPtr {
> > >     private:
> > >       class Tester {
> > >         void operator delete(void*);
> > >       };
> > >     public:
> > >       operator Tester*() const
> > >       {
> > >         if( !IsValid() )
> > >           return NULL;
> > >         static Tester tester;
> > >         return tester;
> > >       }
> > >       // ...
> > >   };
> [...]
> >Aha, yet another approach :-)
> >
> >The suggestions - _all_ of them - all have their merits and all can all work
> >extremely well, but, just like the search the One True String Class, there 
> >is no
> >absolute best answer to this. Shame really.
> [...]

  So what's the drawback of this one? 

  Schobi