doxygen-users — List for users of doxygen

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: [Doxygen-users] DOT Tool for windows

[Emilio R. <Emi...@ma...>]

From AT&T research site:

http://www.research.att.com/sw/tools/graphviz

Emilio Riva







Rol...@jo... on 11/06/2001 11.14.06

Please respond to dox...@li...
                                                                                
                                                                                
                                                                                


                                                              
                                                              
                                                              
 To:      dox...@li...                 
                                                              
 cc:      (bcc: Emilio Riva/MAIN/MC1)                         
                                                              
                                                              
                                                              
 Subject: [Doxygen-users] DOT Tool for windows                
                                                              







Hello everybody!

>From where can I get the graphical visualization toolkit (DOT-Tool) for
Doxygen running under Windows ??

Thanks a lot for your help!

Roland



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

[Doxygen-users] Can doxygen be built with CYGWIN?

[Magnus Lewis-S. <Mag...@pa...>]

Has anyone succeeding in building doxygen under CYGWIN?  I have tried (using "configure --platform gnu-g++"), but always bomb out when compiling config.cpp:

cygwin$ configure --platform gnu-g++
	... output from configure suggests everything OK ...

cygwin$ make
	... output from make OK up to here ...

g++ -c -Wall -W -O2 -I../qtools -o ../objects/config.o config.cpp
	... long pause ...

config.l: In method `void Config::create()':
config.l:2064: virtual memory exhausted
make[2]: *** [../objects/config.o] Error 1
make[2]: Leaving directory `/home/lewis_m/doxygen-1.2.7/src'
make[1]: *** [all] Error 2
make[1]: Leaving directory `/home/lewis_m/doxygen-1.2.7/src'
make: *** [all] Error 2

Any ideas?

--
Magnus Lewis-Smith
Software Engineer Common Code Group
Pace Micro Technology plc.

[Doxygen-users] Doxygen-1.2.8.1 - \ingroup and tagfiles don't mix well

[Walter F.J. M. <W.F...@gs...>]

Hi,

I've a few files with global functions where the documentation is
organized with \ingroup, like

   /*!
     \ingroup CTBmath
     ... some text
   */
   double CTBsqrt(double x) {...}

It still seems to work in the project where the functions are
defined. However, reading the generated tagfile in another project
leads to a boatload of messages, like

    CTBbase.tagfile:/u/mueller/CTB/CTBbase/CTBmath.cxx:1 Warning: 
        no matching class member found for CTBmath.cxx::CTBsqrt()    

or

   CTBbase.tagfile:/u/mueller/CTB/CTBbase/CTBmath.cxx:1 Warning: 
        member CTBlog10 of class CTBmath.cxx cannot be found



			With best regards,	Walter
   

--
Walter F.J. Mueller   Mail:  W.F...@gs...
GSI,  Abteilung KP3   Phone: +49-6159-71-2766
D-64291 Darmstadt     FAX:   +49-6159-71-2989
WWW:   http://www-kp3.gsi.de/www/kp3/people/mueller.html

RE: [Doxygen-users] DOT Tool for windows

[Prikryl,Petr <PRI...@sk...>]

Hi Roland,

Roland Schwab wrote...
> From where can I get the graphical visualization toolkit (DOT-Tool) for
> Doxygen running under Windows ??

As stated in the Doxygen documentation (Graphs and diagrams), the dot
tool can be downloaded from http://www.research.att.com/sw/tools/graphviz/.
More precisely, the
http://www.research.att.com/sw/tools/graphviz/download.html
is the download page.

The Graphviz 1.7.6 beta 1 for Windows is available now (the notice about
version 1.5 in Doxygen documentation is slightly obsolete).  I personally
did not observe any serious problem with the beta version from Doxygen 
-- except the cut top line of some boxes (I do not know if it is the Doxygen
problem or the dot problem).

With regards,

Petr

-- 
Petr Prikryl, SKIL, spol. s r.o., pri...@sk...

[Doxygen-users] DOT Tool for windows

[<Rol...@jo...>]

Hello everybody!

>From where can I get the graphical visualization toolkit (DOT-Tool) for
Doxygen running under Windows ??

Thanks a lot for your help!

Roland

Re: [Doxygen-users] EXPAND_AS_DEFINED and Poor Mans Inheritance

[Peter S. <pet...@hu...>]

On Sun, 10 Jun 2001 23:02:34 +0200, Hendrik Schober wrote:

> "Peter Steiner" <pet...@hu...> wrote:

>> [...]
>> It seems that the doxygen comments inside my macro BASECLASS are
>> swallowed during the preprocessing stage. 

>   AFAIK that's what the C++ standard says how it should be. 

Where does it state this? A very quick glance at section 2.7 (Comments)
and chapter 16 (Preprocessing Directives) didn't give any statement
_when_ to remove comments. To be exactly, I'm more interested in the C
standard in this case anyway, as the source is C (or I'd be able to use
C++ inheritance instead of some obscure macro technology...)

And as doxygen does not see the fully preprocessed source
(or it wouldn't see _any_ comment), it doesn't really matter what the
C++ or C standard says...

>   If your compiler('s preprocessor) behaves differently 
>   then that's either a bug or feature of it. ;^> 

My compiler's preprocessor does what it should: it removes this
comments. But doxygen doesn't use the compilers preprocessor, it uses
its own. I just plea for this _feature_ inside doxygen...

Regards

Peter
-- 
    _   _        Peter Steiner <pet...@hu...>
  / /_/ /        Hug-Witschi AG <http://www.hugwi.ch/>
 /  _  /         Electronic Engineering
/_/ /_/  _   _   Industriestrasse 12
   / / / / / /   CH-3178 Boesingen
  / /_/ /_/ /    Tel  +41 31 740 44 44
 /_ _ _ _ _/     Fax  +41 31 740 44 45

[Doxygen-users] Doxygen-1.2.8.1 and RH7.1

[Holger M. <hmu...@si...>]

Hi Dimitri,

thanks for release 1.2.8.1 which fixes (most) of the 1.2.8 bugs.

I use RedHat 7.1 and have a new problem (?) with this release. You
changed the install tool:

(hmueller@mrwork)~/src/doxygen> cvs diff -r 1.69 configure
Index: configure
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
RCS file: /u/kp3softd/cvsroot/configure,v
retrieving revision 1.69
retrieving revision 1.70
diff -r1.69 -r1.70
3c3
< # $Id: configure,v 1.69 2001/06/04 14:15:19 dimitri Exp $
---
> # $Id: configure,v 1.70 2001/06/10 14:32:12 dimitri Exp $
27c27
< f_insttool=3Dinstall
---
> f_insttool=3Dginstall


but RH 7.1 does not ship ginstall (only install), which is in fact
ginstall:

(hmueller@mrwork)~/src/doxygen> install --version
install (GNU fileutils) 4.0.36
Written by David MacKenzie.

Copyright (C) 2000 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is N=
O
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOS=
E.


but (again ;-)) this is not the mayor problem. You forget to change the
configure documentation:

(hmueller@mrwork)~/src/doxygen> ./configure --help
Usage: ./configure [--help] [--shared] [--static] [--release] [--debug] =

=2E....
  --install name        Use `name' as the name of the GNU install tool
                        [default: install]
=2E....

Should be "default: ginstall". Prefered for me is of course the install
tool instead of ginstall ;-)

Cheers
Holger
-- =

=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
Holger M=FCller, Dipl.-Ing.                          Tel: +49/7034/92584-=
77
Abt. DOTE - Entwicklung                            Fax: +49/7034/92584-99=

sitronic GmbH
Robert-Bosch-Str. 9                          eMail: hmu...@si...=

D-71116 Gaertringen                          URL: http://www.sitronic.com=

=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D

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: [Doxygen-users] EXPAND_AS_DEFINED and Poor Mans Inheritance

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

"Peter Steiner" <pet...@hu...> wrote:

> [...]
> It seems that the doxygen comments inside my macro BASECLASS are
> swallowed during the preprocessing stage. 

  AFAIK that's what the C++ standard says how it should be. 
  If your compiler('s preprocessor) behaves differently 
  then that's either a bug or feature of it. ;^> 

[...]
> Regards, Peter

  Schobi

[...]

[Doxygen-users] Doxygen-1.2.8.1 in CVS

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

Hi,

Due to some annoying bugs in release 1.2.8, I've decided to put out a
bug fix release labelled 1.2.8.1. Here is what has been fixed/changed:
-----------------------------------------------------------------
+ BUG: Parameters appeared in the documentation for undocumented
       arguments (and twice if they were also documented with @param).
+ BUG: Specifying boolean tags twice in the config file resulted in
       an invalid value (both boolean values were appended).
+ BUG: When a paragraph header was directly followed by an
       item list doxygen did not render the first item properly.
+ BUG: The "More..." link was often omitted for grouped members.
+ BUG: "dangerous" characters like ":" are now escaped from man page
       file names.
+ BUG: Fixed a number of typos (thanks to Jens Seidel).
+ CHG: Enum values of a grouped (with @ingroup) enum are now automatically
       added to the same group.
+ ADD: Included update for Brazilian translation.
+ ADD: Add support for < > & ' " in the documentation,
       since these commands after occur in Java documentation.
-----------------------------------------------------------------
Enjoy,
  Dimitri

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

RE: [Doxygen-users] filename problem in 1.2.8

[Trevor R. <Tre...@pe...>]

Yes, come to think of it, it was the man page output and not HTML.  So I
guess it's not a big deal for Windows (although someone COULD potentially
run man on NT).  ;-)  I just wanted to let you know that it used to work
okay and now it doesn't, in case anyone else cares.

-Trevor

-----Original Message-----
From: Dimitri van Heesch [mailto:di...@st...]
Sent: Friday, June 08, 2001 1:12 PM
To: dox...@li...
Subject: Re: [Doxygen-users] filename problem in 1.2.8


On Fri, Jun 08, 2001 at 11:19:56AM -0500, Trevor Robinson wrote:
> Dimitri,
> 
> I've run into a problem introduced in 1.2.8 on Windows.  I have a class
that
> derives from "std::bad_alloc".  Therefore, Doxygen tries to generate
> documentation for that class.  The problem is that is wants to name the
file
> "std::bad_alloc.html" or something similar.  Windows is not too keen on
> creating filenames with colons (":") in them, so Doxygen aborts saying it
> can't create the file.  Doxygen 1.2.7 named the file
> "classstd_1_1bad__alloc.html".

For HTML the same naming scheme should still be used. It's the man
pages that are generated with names that could include colons. For
Windows I suggest to disable man page output, while I work on a fix that
generates less "dangerous" names.

Regards,
  Dimitri


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

Re: [Doxygen-users] filename problem in 1.2.8

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

On Fri, Jun 08, 2001 at 11:19:56AM -0500, Trevor Robinson wrote:
> Dimitri,
> 
> I've run into a problem introduced in 1.2.8 on Windows.  I have a class that
> derives from "std::bad_alloc".  Therefore, Doxygen tries to generate
> documentation for that class.  The problem is that is wants to name the file
> "std::bad_alloc.html" or something similar.  Windows is not too keen on
> creating filenames with colons (":") in them, so Doxygen aborts saying it
> can't create the file.  Doxygen 1.2.7 named the file
> "classstd_1_1bad__alloc.html".

For HTML the same naming scheme should still be used. It's the man
pages that are generated with names that could include colons. For
Windows I suggest to disable man page output, while I work on a fix that
generates less "dangerous" names.

Regards,
  Dimitri

Re: [Doxygen-users] filename problem in 1.2.8

[Luigi B. <lui...@ri...>]

At 11:19 AM 6/8/01 -0500, you wrote:
>Dimitri,
>
>I've run into a problem introduced in 1.2.8 on Windows.  I have a class that
>derives from "std::bad_alloc".  Therefore, Doxygen tries to generate
>documentation for that class.  The problem is that is wants to name the file
>"std::bad_alloc.html" or something similar.  Windows is not too keen on
>creating filenames with colons (":") in them, so Doxygen aborts saying it
>can't create the file.  Doxygen 1.2.7 named the file
>"classstd_1_1bad__alloc.html".

You can set SHORT_NAMES to YES to have the files named as a0143.html or 
something like it (index.html will still be called index.html).

Bye,
         Luigi

[Doxygen-users] filename problem in 1.2.8

[Trevor R. <Tre...@pe...>]

Dimitri,

I've run into a problem introduced in 1.2.8 on Windows.  I have a class that
derives from "std::bad_alloc".  Therefore, Doxygen tries to generate
documentation for that class.  The problem is that is wants to name the file
"std::bad_alloc.html" or something similar.  Windows is not too keen on
creating filenames with colons (":") in them, so Doxygen aborts saying it
can't create the file.  Doxygen 1.2.7 named the file
"classstd_1_1bad__alloc.html".

Thanks,
Trevor

[Doxygen-users] hide undocumented enum

[<dav...@ca...>]

Hi all,

I have to document some C includes with the doxygen format. I don't want to
document some
structures and enumarates.

configuration options are the following:

 EXTRACT_ALL            = NO
 EXTRACT_PRIVATE        = NO
 EXTRACT_STATIC         = NO
 HIDE_UNDOC_MEMBERS     = YES
 HIDE_UNDOC_CLASSES     = YES

After generation the undocumented structures are not in the html documentation
but the
undocumented enumarates appears.

Best regard

David Gaumont

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

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

I'll try to answer best I can......  replies in the text
At Friday 2001/06/08 06:53, you wrote:
>[Just found this sitting unsent in my outbox and its still an interesting C++
>issue, so:]
>
> > -----Original Message-----
> > From: dox...@li...
> > [mailto:dox...@li...]On Behalf Of Wagner,
> > Victor
> > Sent: 08 May 2001 14:16
> > To: 'dox...@li...'
> > Subject: RE: (off-topic) RE: [Doxygen-users] Documenting IDL
> >
> >
> > I didn't say operator int(), I said operator void* ().  There
> > is a large
> > difference.
>
>When starting this, I deliberately avoided addined an operator that could be
>mistakenly read as returning more information than it does - something that
>returns 'bool' is unambiguous, even the most neophyte "next new guy to 
>join the
>team" isn't going to try and cast it to anything (which sounds a bit rude and
>snotty, but it is exactly the sort of thing that has happened).
>
>So far as any other code is concerned, _what_ is this large difference? 
>The only
>use for this operator is in a test such as "if (ptr)" and bool seems to 
>fit that
>idea quite nicely.

But it isn't really a bool.  If you write operator bool() then it could be 
used anywhere a bool is valid (not just in if and while).
I'm just following several authors dictum (when in doubt, do what the built 
in types do...in this case, I consider the STL 'built in')


> > the problem of 'adding' your own test is that it isn't the same as:
> > real pointers
>
>Very true - for example, with 'real pointers' I wouldn't get upset if people
>wrote all their functions calls as Fum(MyPointer fred) whereas with 
>ref-counted
>pointers, for example, you want to write Fum(const MyPointer& fred). These are
>not 'real pointers' and sometimes it is good to be reminded of this (and
>sometimes it is bad).
>
> > STL iterators
>
>Well, I admit to not having tried to combine the two (remember, this all 
>started
>from old code, VC++2 days, which rather pre-dates a (working) copy of STL 
>being
>available). If (when?) it becomes necessary to combine the two, that does not
>preclude leaving in 'IsValid()' - after all, to be an iterator you just 
>need to
>provide the correct interface and after that you can add anything else you 
>want.
>
>One day, no doubt, the two will coincide, when someone wants to feed one of
>these pointers to an STL algorithm, at which time it would be useful to know
>what the large difference is between using operator bool() and operator void
>*() - does the former stop something working?
>
>Regards,
>Stephen Goudge

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"

[Doxygen-users] Problem with Makros

[Martini, M. <M.M...@Ve...>]

Hi all,

I'm novice to doxygen. In our project we use version 1.2.6. (Windows
Version) and we have sourcecode like this:

Header:
class _CLASSTYPE CImpIAutoApplication : public IAutoApplication
{
/* ... */
public:
	STDMETHOD_(ULONG, AddRef)(THIS) ;
/* ... */
};

The implementation:
STDMETHODIMP_(ULONG) CImpIAutoApplication::AddRef()
{
	return ++m_ulRefCnt;
}


Then I inserted a few comments for all methods that belongs to that class.
Doxygen identifies all comments except those for methods like this AddRef().
The documentation looks like doxygen indentifies STDMETHODIMP_ as a method
name of my class. 

I use the following settings:
ENABLE_PREPROCESSING   = YES
MACRO_EXPANSION        = YES
EXPAND_ONLY_PREDEF     = NO
SEARCH_INCLUDES        = YES

I tried another syntax:
Declaration:
ULONG STDMETHODCALLTYPE AddRef();

Implemetation:
ULONG STDMETHODCALLTYPE CImpIAutoApplication::AddRef()

With this syntax it works fine.

I think that the makro expansion does not work on some unknown reason and
that doxygen identifies the first right parenthesis as the end of the method
name.
But we have so much generated code that looks like the sample above.
Therefore I hope that someone has an idea how doxygen can manage this
without changing the syntax.

Best regard
Michael Martini

Re: [Doxygen-users] Function overloading parameters double.

[Erich O. <eri...@er...>]

Olaf Baeyens wrote:
> I have noted that with Doxygen 1.2.8 the Parameters are written 2 times.
> One time with the description following and one time without

I've noticed this too and have sent an email to Dimitri on Tuesday.
Let's hope the problem will soon be fixed.

-- Erich

[Doxygen-users] Function overloading parameters double.

[Olaf B. <ola...@sk...>]

I have noted that with Doxygen 1.2.8 the Parameters are written 2 times.
One time with the description following and one time without

I don't recall v1.2.7 to have this problem.

I love the jump functionality when you see the source code in HTML. If
you click on the function it jumps to the functon definition. But I also
noted that sometimes, in the case of overloading (like below), the wrong
function is jumped to.

Code examples below.

Thanks in advance.
Keep up the good work!

Next folowing the function definitions
--------------------------------------
		/// Reads a double from the Skyscan registry location
(System or User)
		/*! Dependend on m_bUserMode, we either read from the
System or User registry.
			@return The double on success else the default
value
			@param asProfile	Base path in the
registry. \n	e.g. "Skyscan-1074\\Profile\\"
			@param asSection	Subsection in the
registry. \n e.g. "Default"
			@param asKey		The key to read from.
\e.g. "MyKey"
			@param aDefault		The default double value
if the read failes or the key does not exist
			\see m_bUserMode, m_sProfilePath, m_sProfileFile
*/
	double ReadDouble(const string &asProfile, const string
&asSection, const string &asKey, double aDefault);
		/// Reads a double from the Skyscan registry location
(System or User)
		/*! Dependend on m_bUserMode, we either read from the
System or User registry. \n
			Uses m_sProfilePath and m_sProfileFile as
destination..
			@return The double on success else the default
value
			@param asKey		The key to read from.
\e.g. "MyKey"
			@param aDefault		The default double value
if the read failes or the key does not exist
			\see m_bUserMode, m_sProfilePath, m_sProfileFile
*/
	double ReadDouble(const string &asKey,double aDefault);

Next what Doxygen created
-------------------------
BOOL CSkyScanReg::WriteInt (  const string & asKey, =20
 int aiValue ) =20
=20
   Writes an integer to the Skyscan registry location (System or User).=20

Dependend on m_bUserMode, we either write to the System or User
registry.=20
Uses m_sProfilePath and m_sProfileFile as destination..=20

Returns:=20
	TRUE on success=20
	Parameters:=20
		asKey   The key to write to. \e.g. "MyKey" =20
		aiValue   The integer value to write =20

	See also:=20
		m_bUserMode, m_sProfilePath, m_sProfileFile=20
>>>	Parameters: 			<<< double????????
>>>		asKey    			<<< double????????
>>>		aiValue    			<<< double????????=09

00062 {
00063         return WriteInt(m_sProfilePath,
m_sProfileFile,asKey,aiValue);
00064 }

=20

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

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

[Just found this sitting unsent in my outbox and its still an interesting C++
issue, so:]

> -----Original Message-----
> From: dox...@li...
> [mailto:dox...@li...]On Behalf Of Wagner,
> Victor
> Sent: 08 May 2001 14:16
> To: 'dox...@li...'
> Subject: RE: (off-topic) RE: [Doxygen-users] Documenting IDL
>
>
> I didn't say operator int(), I said operator void* ().  There
> is a large
> difference.

When starting this, I deliberately avoided addined an operator that could be
mistakenly read as returning more information than it does - something that
returns 'bool' is unambiguous, even the most neophyte "next new guy to join the
team" isn't going to try and cast it to anything (which sounds a bit rude and
snotty, but it is exactly the sort of thing that has happened).

So far as any other code is concerned, _what_ is this large difference? The only
use for this operator is in a test such as "if (ptr)" and bool seems to fit that
idea quite nicely.

> the problem of 'adding' your own test is that it isn't the same as:
> real pointers

Very true - for example, with 'real pointers' I wouldn't get upset if people
wrote all their functions calls as Fum(MyPointer fred) whereas with ref-counted
pointers, for example, you want to write Fum(const MyPointer& fred). These are
not 'real pointers' and sometimes it is good to be reminded of this (and
sometimes it is bad).

> STL iterators

Well, I admit to not having tried to combine the two (remember, this all started
from old code, VC++2 days, which rather pre-dates a (working) copy of STL being
available). If (when?) it becomes necessary to combine the two, that does not
preclude leaving in 'IsValid()' - after all, to be an iterator you just need to
provide the correct interface and after that you can add anything else you want.

One day, no doubt, the two will coincide, when someone wants to feed one of
these pointers to an STL algorithm, at which time it would be useful to know
what the large difference is between using operator bool() and operator void
*() - does the former stop something working?

Regards,
Stephen Goudge


> -----Original Message-----
> From: Stephen Goudge [mailto:ste...@pi...]
> Sent: Tuesday, 2001 May 08 09:31
> To: dox...@li...
> Subject: (off-topic) RE: [Doxygen-users] Documenting IDL
>
> [deleted]
>
> 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
>
>
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> http://lists.sourceforge.net/lists/listinfo/doxygen-users
>
>
> This transmission may contain information that is privileged,
> confidential
> and exempt from disclosure under applicable law.
> If you are not the intended recipient, you are hereby
> notified that any
> disclosure, copying, distribution, or use of the information contained
> herein (including any reliance thereon) is STRICTLY PROHIBITED.
> If you received this transmission in error, please
> immediately contact the
> sender and destroy the material in its entirety, whether in
> electronic or
> hard copy format.
> Thank you
>
>
>
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> http://lists.sourceforge.net/lists/listinfo/doxygen-users
>

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

[Doxygen-users] Member grouping problem

[Olaf B. <ola...@sk...>]

I love Doxygen, but I have a small problem with member grouping.
The HTML file does not generate the group at all.

Below is a part of the code I used.
What am I doing wrong? I didn't find a configuration setiign to activate
member grouping.

I am using Win98, Doxygen v1.2.8 and only generate HTML code.

------------------
 //@name Application related paths
 //@{=20
  /// Our path and filename for this application
  string  m_sApplicationFileName;
   /// Path of our application
  string  m_sApplicationPath;
   /// Path to our configuration. (Black fileds white fields, random set
*/
  string  m_sConfigPath;
   /// Path to our help
  string  m_sHelpPath;
   /// Scan result destination path to store the files
  string  m_sScanResultPath;
   /// Prefix file name to store the scan result, works in combination
with m_sScanResultPath
   /*! \see m_sScanResultPath */
  string  m_sScanFilePrefix;
 //@}

------------------

Thanks in advance

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