doxygen-users — List for users of doxygen

[Doxygen-users] Glitches

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

Hi all (and especially Dimitri),
	I found a few small glitches in the generation of cross-links between 
brief and detailed docs in derived classes. The comments in the attached 
file should tell the whole story. The strange behavior is triggered by 
generating a fresh Doxyfile and setting
INPUT                  = test.cpp
REPEAT_BRIEF           = NO

Thanks,
	Luigi

RE: [Doxygen-users] Class collaboration [LONG]

[Kris T. <kri...@ic...>]

This is fun indeed. Maybe not practical, but ok...

> DEFINITION:
> 	Class A is CONTAINED in class B if and only if class B has
> an instance (not pointer or reference) member variable to class A.
>
fine for me

> DEFINITION:
> 	Class A is USED-BY class B if and only if in some member
> functions of class B invokes a member function of class A.
>
> 	(I say member function, because we make all our member variables
> private, right?)
>
fine for me as well. Except that I would include member variables in the
definition. That way, you wouldn't have to add anything specific for friends
below (if it's a friend, but doesn't use any of its members, there wasn't a
point in having it a friend anyway).

Here's one practical problem for doxygen: to decide on this, it would have
to parse the actual C++ code, and in particular the implementations of the
member functions. I don't think doxygen does this, and I don't think it
would be easy. Sounds much more like real compilation to me.

In particular, for nearly all purposes, you can get away with doxygening
only the .h files (except of you put doxygen comments in .cxx).

> 	struct A { void Foo(void){} };
>
> CASE I (Instance)
> 	1) class B { A a; void Bar(void) {a.Foo();} };
> 	2) class B { A a[10]; void Bar(void) {a[0].Foo();} };  //  ??
> 	3) class B { void Bar(A a) {a.Foo();} };
> CASE II (Pointer)
> 	1) class B { A *a; void Bar(void) {a->Foo();} };
> 	2) class B { void Bar(A *a) {a->Foo();} };
> CASE III (Reference)
> 	1) class B { A &a; void Bar(void) {a.Foo();} };
> 	2) class B { void Bar(A &a) {a.Foo();} };
>
> 	We need to be careful in handling cases II and III, because
> B does not necessarily invoke any public member function of A...
> However, in reality, Doxygen simply concludes that class A is USED-BY
> Class B in cases II.1 and III.1  It does not consider II.2 or III.2
> Perhaps it should?
>

I.2 seems an obvious candidate as well

>
> DEFINITION:
> 	Class A is DIRECTLY-RELATED to class B if and only if class
> A is CONTAINED in class B, or class A is USED-BY class B, or class
> B is a FRIEND to class A.
>

fine for me.


> CASE IV (Template)

tough and so on. But I'm afraid that if you don't handle it, a lot of my
code will not see any benefit if all this.

> >  "Is the result of a solution of the problem worth of the
> >   complexity of the solution?"
>
> 	Probably not...  Oh well, life is full of tradeoff's.  :)
>
if you ask me, it means that 'collaboration diagrams' are very diffiuclt to
make sensible. In such a case, it is better to disable them in my opinion.
Incomplete doc is more confusing than no doc.
In any case, I can get so graphs in my doc from doxygen nowadays that it all
looks stunning enough already!


> 	It has been fun typing this message.  Thank you for
> your time if you made it this far.

you're welcome.

Kris Thielemans
Imaging Research Solutions Ltd
Cyclotron Building
Hammersmith Hospital
Du Cane Road
London W12 ONN, United Kingdom


web site address:
http://www.irsl.org/~kris

FW: [Doxygen-users] Class collaboration

[Wagner, V. <VW...@se...>]

Sorry, I forget to hit 'reply all'

-----Original Message-----
From: Wagner, Victor 
Sent: Thursday, 2001 September 13 15:46
To: 'Dimitri van Heesch'
Subject: RE: [Doxygen-users] Class collaboration


IMO, it is far more important to know that
std::vector<Widget*> gorph;
is about Widget*s than std::vector.... mayhaps when you show the 'name' of
the var involved with the collaboration, you could show it simply by showing
the entire definition instead of just the name...or drop out the Class name
for consistency with my proposal in the 'nit' paragraph.
std::vector<*> gorph
and place it next to the 'arrow' pointing to Widget

NIT
BTW, minor nit (and not big enough to comment on until I'm commenting on
something closely related)
when we have the arrows in the collaboration graph, there is NO distinction
between member objects, member pointers to objects or member references to
objects (might be nice).... syntax for pointer and reference are easy (* and
& respectively adjacent to the name)

I'm immensely pleased with Doxygen, keep up the good work.

-----Original Message-----
From: Dimitri van Heesch [mailto:di...@st...]
Sent: Thursday, 2001 September 13 14:52
To: dox...@li...
Subject: Re: [Doxygen-users] Class collaboration


On Thu, Sep 13, 2001 at 12:51:43PM -0300, Anthony Yuen wrote:
> 
> 	Hi, I found another "problem" that "bugs" me (pun intended!).
> In the class collaboration diagram that is generated, I think something
> is not quite right.  Let me give an example:
> 
> 	class A { /* some methods */ };
> 
> 	class B { std::vector<A *> vec; };
> 
> 	I'm just using the std::vector as an example.  It can be any
> kind of (STL) container.  Even though this strongly suggests that
> class B somehow uses class A for "something" (in my case, B *does*
> make use of A, which is why B stores a vector of pointers to A),
> Doxygen does not conclude that there is collaboration between A and B.
> This can be extended to include the use of smart pointers stored
> in a container.
> 
> 	I'm interested to know if this is the intended behaviour.  If
> so, what is the reason behind?  If not, maybe this is a bug?

Currently this is intended behaviour, but I would like to hear what other 
people think about this. Should template arguments, such as in the example 
above, be visualised in collaboration diagrams? and if so, how? Does UML
cover these kind of relations?

Regards,
  Dimitri

_______________________________________________
Doxygen-users mailing list
Dox...@li...
https://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

RE: [Doxygen-users] Class collaboration

[Anthony Y. <an...@ac...>]

	I'm a rather lazy person and that's the whole reason I'm using
a tool such as Doxygen to automatically generate some nice reference
manuals from my messy source code.  :)  But I agree that it would
be nice to have the option when you REALLY need it!  But most of the
time, I would avoid doing anything "manually" when writing "manuals".
:)

	Happy Doxygening!  I'm quite impressed by the quality of the
generated materials by Doxygen.  I'm a happy users (with some minor
complaints/whines/rants).  :)


-----Original Message-----
From: dox...@li...
[mailto:dox...@li...] On Behalf Of
Prikryl,Petr
Sent: Friday, 14 September, 2001 09:32
To: dox...@li...
Subject: RE: [Doxygen-users] Class collaboration

Hi Kris,

I agree that adding some extra command to manually mark the
relation between the classes would be fine.  Majority probably
do not need some general solution of that kind.  Those who need
to capture the relationship of that special kind would probably
agree to insert it manually.  I cannot argue here.  I belong to the
majority ;-)

Petr

--

RE: [Doxygen-users] Class collaboration [LONG]

[Anthony Y. <an...@ac...>]

	Let me take the discussion a little further since I started
it...
A fair warning, it is a bit long...

[snip]

>  "Should only direct relations be considered in the
>   collaboration diagram?"


	My answer to this question is YES.  But it would be helpful
to define exactly what "direct relation" is.  I'll quote from
the "graph legend":

	"A purple dashed arrow is used if a class is contained
	or used by another class. The arrow is labeled with the
	variable(s) through which the pointed class or struct
	is accessible."

	So, in fact, keep in mind that Doxygen already considers (plain)
pointers to another class as a collaboration.  This means the "level of
indirect relation" is 2 (see below).  Then why does Doxygen put
a "purple dashed arrow" if there is a "pointed class" inside
another class?  Let's examine a possible reason for that.

	It is clear what "a class is contained" means.  It means
that: if class B has an instance member variable to class A, then
we say "class A is contained in B".  Should a pointer to class A count
as "contained in" too?  No, I don't think so.  Even if sizeof(A)
changes,
sizeof(B) doesn't, because B only contains a pointer (or reference).
This is a proof that class A is *not* contained in class B.

DEFINITION:
	Class A is CONTAINED in class B if and only if class B has
an instance (not pointer or reference) member variable to class A.

	This leaves us the second way to get a "purple dashed arrow",
which is when class A is "used" by class B.  But what is "used"?
How do you define "used"?  Here is a reasonable definition:

DEFINITION:
	Class A is USED-BY class B if and only if in some member
functions of class B invokes a member function of class A.

	(I say member function, because we make all our member variables
private, right?)

	Obviously, this includes (public, protected, private)
inheritance
relationships, since a derived class, at the minimum, must invoke
the base class constructor(s) and destructor.  Doxygen handles these
separately.

	Exploring further, we see that if class B invokes a public
member function of class A, then class A is USED-BY class B.  How is
this
possible?  There are 3 ways in C++: instance, pointer, reference.

	struct A { void Foo(void){} };

CASE I (Instance)
	1) class B { A a; void Bar(void) {a.Foo();} };

	2) class B { A a[10]; void Bar(void) {a[0].Foo();} };  //  ??

	3) class B { void Bar(A a) {a.Foo();} };

CASE II (Pointer)
	1) class B { A *a; void Bar(void) {a->Foo();} };

	2) class B { void Bar(A *a) {a->Foo();} };

CASE III (Reference)
	1) class B { A &a; void Bar(void) {a.Foo();} };

	2) class B { void Bar(A &a) {a.Foo();} };


	We need to be careful in handling cases II and III, because
B does not necessarily invoke any public member function of A...
However, in reality, Doxygen simply concludes that class A is USED-BY
Class B in cases II.1 and III.1  It does not consider II.2 or III.2
Perhaps it should?

	Should a friend class be considered a collaboration?  Sure.
Otherwise, the two classes shouldn't be friends in the first place.
The reason you made class B a FRIEND to class A is so that B can
invoke protected or private member functions of A...  Doxygen does not
handle this case either.

	In conclusion, what is a "direct relation"?

DEFINITION:
	Class A is DIRECTLY-RELATED to class B if and only if class
A is CONTAINED in class B, or class A is USED-BY class B, or class
B is a FRIEND to class A.

	The above is my humble opinion on what a "direct relation" is.
It is by no means exhaustive or scientifically rigorous.


>If the answer is no, then main() (for example) is a
>function that is indirectly related to almost everything
>in the program -- except the part hidden in
>implementation parts (.c, .cpp).  If I use here some
>object of the class that hides inside the whole
>functionality of the application, then the collaboration graph
>of that class would be very complex and it would contain almost
>every class of the application.  (Well, this is rather.
>simplified, but I hope you understand the point.)


	Yes, I see a problem here, if the "level of indirect
Relation" is allowed to be "infinity".


>If the above were accepted, then the only reasonable
>solution would be to define the maximum level of indirect
>relations.  Say, 1 (one) is the level when we think only
>about direct relations.


	Agreed, if you consider my definition of a direct relation.


>Now, std::vector<A> is a vector of instances of class A.
>The mentioned example of std::vector<A *> is vector of
>pointers to such instances.  Even when you know how
>std::vector<whatever> may look like inside---from the abstract
>point of view---you should agree that the "whatever" is hidden
>inside something lager.  If "vec" is the object of that class, then
>"whatever" is somehow hidden inside.  So, I would mark
>the level of collaboration between B and "whatever" using
>at least value 2.  Moreover, if the "whatever" is a
>pointer to "something-else", I would mark the level of
>collaboration between B and "something-else" using at
>least the value 3.


	I agree that "whatever" is hidden.  But if class B invokes
a public member function of class A, through the vector or
some other kind of container, then class A is USED-BY class B.

	Another way of "justifying" a collaboration between A
and B is that, std::vector<A> (or std::vector<A *>) is a type
that depends on A.  So A is USED-BY B to create a new type.
Hence, we have a CASE IV:

CASE IV (Template)
	1) template <typename T> class B {};  B<A> b;

	2) class B { template <typename T> void Bar(void){} };
	   B b; b.Bar<A>();

	3) class B { some_template<A> t_a; };

	Of course, there are many variations on this theme, but
I hope you get the idea.

	This CASE IV is what complicates things by many orders of
magnitudes.  And I wouldn't want to be the person to try to
solve it.  :)


>Even more serious problem is that the argument of any
>template is used textually inside the body of the
>template.  This also means that you do not exactly know
>how it is used.


	We know how it is used -- to create a new type using
the template!


>	To conclude, I guess that generally it would be very
>difficult to build the collaboration diagram correctly if
>the template arguments should be followed.


	Agreed.  May be this is an NP-Hard problem.  :)


>On the other hand, the life is not only that much
>scientific.  It could probably be useful to include some
>internal knowledge about standard containers into doxygen.
>But then, you have to know whether "vector<something>"
>means _some_ vector or std::vector<>, etc.  In other words,
>the parser would be probably more complicated.


	Agreed, so I "forgive" Doxygen for not handling the
CASE IV.  But, still, what about CASE II.2 and III.2?


>So, the final question is:
>
>  "Is the result of a solution of the problem worth of the
>   complexity of the solution?"


	Probably not...  Oh well, life is full of tradeoff's.  :)

	It has been fun typing this message.  Thank you for
your time if you made it this far.

RE: [Doxygen-users] Class collaboration

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

Hi Kris, 

I agree that adding some extra command to manually mark the 
relation between the classes would be fine.  Majority probably 
do not need some general solution of that kind.  Those who need
to capture the relationship of that special kind would probably
agree to insert it manually.  I cannot argue here.  I belong to the
majority ;-)

Petr

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

> -----Original Message-----
> From:	Kris Thielemans [SMTP:kri...@ic...]
> Sent:	Friday, September 14, 2001 12:26 PM
> To:	dox...@li...
> Subject:	RE: [Doxygen-users] Class collaboration
> 
> Dear Petr,
> 
> I agree with you. It seems impossible to do this without knowing what
> std::vector is. One could argue this is easy to do, but what about by own
> class Array. Can doxygen know it's also a container class? Too hard.
> 
> > > > [...] In the class collaboration diagram that is generated,
> > > > I think something is not quite right.  Let me give an example:
> > > >
> > > > 	class A { /* some methods */ };
> > > > 	class B { std::vector<A *> vec; };
> >
> >   "Is the result of a solution of the problem worth of the
> >    complexity of the solution?"
> 
> So, I don't think anyone should try to build this in in the parser.
> However,
> it might be useful to have an extra doxygen command (one more!) to force a
> class to be put in the collaboration diagram. That would solve this
> conundrum I guess.
[...]

RE: [Doxygen-users] Class collaboration

[Kris T. <kri...@ic...>]

Dear Petr,

I agree with you. It seems impossible to do this without knowing what
std::vector is. One could argue this is easy to do, but what about by own
class Array. Can doxygen know it's also a container class? Too hard.

> > > [...] In the class collaboration diagram that is generated,
> > > I think something is not quite right.  Let me give an example:
> > >
> > > 	class A { /* some methods */ };
> > > 	class B { std::vector<A *> vec; };
> > >
>
>   "Is the result of a solution of the problem worth of the
>    complexity of the solution?"
>

So, I don't think anyone should try to build this in in the parser. However,
it might be useful to have an extra doxygen command (one more!) to force a
class to be put in the collaboration diagram. That would solve this
conundrum I guess.

All the best,

Kris Thielemans
Imaging Research Solutions Ltd
Cyclotron Building
Hammersmith Hospital
Du Cane Road
London W12 ONN, United Kingdom


web site address:
http://www.irsl.org/~kris

RE: [Doxygen-users] Class collaboration

[Schreib, D. VTC-B. <dir...@vo...>]

> > In the 
> > class collaboration diagram that is generated, I think something is 
> > not quite right.  Let me give an example:
> > 
> > 	class A { /* some methods */ };
> > 
> > 	class B { std::vector<A *> vec; };
> > 
> > 	I'm just using the std::vector as an example.  It can 
> be any kind of 
> > (STL) container.  Even though this strongly suggests that class B 
> > somehow uses class A for "something" (in my case, B *does* 
> make use of 
> > A, which is why B stores a vector of pointers to A), 
> Doxygen does not 
> > conclude that there is collaboration between A and B. This can be 
> > extended to include the use of smart pointers stored in a container.
> > 
> > 	I'm interested to know if this is the intended 
> behaviour.  If so, 
> > what is the reason behind?  If not, maybe this is a bug?
> 
> Currently this is intended behaviour, but I would like to 
> hear what other 
> people think about this. Should template arguments, such as 
> in the example 
> above, be visualised in collaboration diagrams? and if so, 
> how? Does UML cover these kind of relations?

Take a look at Together C++ / Control Center. This tool visualizes
it as an one-to-many relationship from B to A. (and an aggregation,
if you remove the pointer).

Dirk


---------------------------------------------------------
This Mail has been checked for Viruses
Attention: Encrypted mails can NOT be checked!

**

Diese Mail wurde auf Viren geprueft
Hinweis: Verschluesselte mails koennen NICHT auf Viren geprueft werden!
---------------------------------------------------------

RE: [Doxygen-users] Class collaboration

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

Dimitri wrote:
> Anthony Yuen wrote:
> > 
> > [...] In the class collaboration diagram that is generated,
> > I think something is not quite right.  Let me give an example:
> > 
> > 	class A { /* some methods */ };
> > 	class B { std::vector<A *> vec; };
> > 
> > [...] I'm interested to know if this is the intended behaviour.  If
> > so, what is the reason behind?  If not, maybe this is a bug?
> 
> Currently this is intended behaviour, but I would like
> to hear what other people think about this. Should
> template arguments, such as in the example above, be
> visualised in collaboration diagrams? and if so, how?
> [...]

Shortly, I think that this behaviour is correct.

No so shortly, I feel that it is more philosophic problem
than the technical one (I may be wrong).  So I would
reformulate the question:

  "Should only direct relations be considered in the
   collaboration diagram?"

If the answer is no, then main() (for example) is a
function that is indirectly related to almost everything
in the program -- except the part hidden in
implementation parts (.c, .cpp).  If I use here some
object of the class that hides inside the whole
functionality of the application, then the collaboration graph 
of that class would be very complex and it would contain almost
every class of the application.  (Well, this is rather
simplified, but I hope you understand the point.)

If the above were accepted, then the only reasonable
solution would be to define the maximum level of indirect
relations.  Say, 1 (one) is the level when we think only
about direct relations.

Now, std::vector<A> is a vector of instances of class A.
The mentioned example of std::vector<A *> is vector of
pointers to such instances.  Even when you know how 
std::vector<whatever> may look like inside---from the abstract
point of view---you should agree that the "whatever" is hidden
inside something lager.  If "vec" is the object of that class, then
"whatever" is somehow hidden inside.  So, I would mark
the level of collaboration between B and "whatever" using
at least value 2.  Moreover, if the "whatever" is a
pointer to "something-else", I would mark the level of
collaboration between B and "something-else" using at
least the value 3.

Even more serious problem is that the argument of any
template is used textually inside the body of the
template.  This also means that you do not exactly know
how it is used.

To conclude, I guess that generally it would be very
difficult to build the collaboration diagram correctly if
the template arguments should be followed.

On the other hand, the life is not only that much
scientific.  It could probably be useful to include some
internal knowledge about standard containers into doxygen.
But then, you have to know whether "vector<something>"
means _some_ vector or std::vector<>, etc.  In other words,
the parser would be probably more complicated.

So, the final question is:

  "Is the result of a solution of the problem worth of the
   complexity of the solution?"

With regards,
  Petr

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

[Doxygen-users] Basic question

[Steve W. <ste...@ag...>]

Hi All,

Sorry for the overly simple question but having read through the doco
I cannot under stand why I get the following error messages:

Generating docs for file wdog.c...
Generating docs for file wdog.h...
c:/data/stevew/doxygen/wdog/wdog.h,135,Warning: Member wdCreate of file wdog.h
is not documented.
c:/data/stevew/doxygen/wdog/wdog.h,146,Warning: Member wdDelete of file wdog.h
is not documented.
c:/data/stevew/doxygen/wdog/wdog.h,156,Warning: Member wdStart of file wdog.h is
not documented.
c:/data/stevew/doxygen/wdog/wdog.h,167,Warning: Member wdStop of file wdog.h
isnot documented.
Generating docs for file wdog2.c...
Generating docs for file wdog2.h...
c:/data/stevew/doxygen/wdog/wdog2.h,34,Warning: Member wdShow of file wdog2.h is
not documented.


The wdog.h file is as follows:

/*!	\fn int wdCreate(int wd_id)
	\brief Creates a new instance of a Watch Dog Timer
	\param wd_id A user designated ID for the Watch Dog Timer to be created
*/
int wdCreate(int wd_id);



/*!	\fn int wdDelete(int wd_id)
	\brief Deletes a Watch Dog Timer
	\param wd_id The user assigned ID for the Watch Dog Timer 
*/
int wdDelete(int wd_id);

etc.....

What have I missed, such that I get the warnings above ?


Regards,

Steve Walker.

RE: [Doxygen-users] Class collaboration

[Jeff G. <je...@cr...>]

> Currently this is intended behaviour, but I would like to hear what other
> people think about this. Should template arguments, such as in the example
> above, be visualised in collaboration diagrams? and if so, how? Does UML
> cover these kind of relations?

The case of std::vector<ValueType> seems reasonable, but std::map<KeyType,
ValueType> would be tricky in my mind.  I wouldn't think that we would want the
KeyType in the collaboration diagram although that class is certainly used.

Jeff

Re: [Doxygen-users] Class collaboration

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

On Thu, Sep 13, 2001 at 12:51:43PM -0300, Anthony Yuen wrote:
> 
> 	Hi, I found another "problem" that "bugs" me (pun intended!).
> In the class collaboration diagram that is generated, I think something
> is not quite right.  Let me give an example:
> 
> 	class A { /* some methods */ };
> 
> 	class B { std::vector<A *> vec; };
> 
> 	I'm just using the std::vector as an example.  It can be any
> kind of (STL) container.  Even though this strongly suggests that
> class B somehow uses class A for "something" (in my case, B *does*
> make use of A, which is why B stores a vector of pointers to A),
> Doxygen does not conclude that there is collaboration between A and B.
> This can be extended to include the use of smart pointers stored
> in a container.
> 
> 	I'm interested to know if this is the intended behaviour.  If
> so, what is the reason behind?  If not, maybe this is a bug?

Currently this is intended behaviour, but I would like to hear what other 
people think about this. Should template arguments, such as in the example 
above, be visualised in collaboration diagrams? and if so, how? Does UML
cover these kind of relations?

Regards,
  Dimitri

[Doxygen-users] Class collaboration

[Anthony Y. <an...@ac...>]

	Hi, I found another "problem" that "bugs" me (pun intended!).
In the class collaboration diagram that is generated, I think something
is not quite right.  Let me give an example:

	class A { /* some methods */ };

	class B { std::vector<A *> vec; };

	I'm just using the std::vector as an example.  It can be any
kind of (STL) container.  Even though this strongly suggests that
class B somehow uses class A for "something" (in my case, B *does*
make use of A, which is why B stores a vector of pointers to A),
Doxygen does not conclude that there is collaboration between A and B.
This can be extended to include the use of smart pointers stored
in a container.

	I'm interested to know if this is the intended behaviour.  If
so, what is the reason behind?  If not, maybe this is a bug?

	Thanks for your time.

RE: [Doxygen-users] Sorting member functions (bug?)

[Anthony Y. <an...@ac...>]

	Thanks for your response.  Yes, that's exactly what I'd like to
do.  I know about the option SORT_MEMBER_DOCS but it only sorts the
detailed descriptions, *NOT* the brief descriptions, where the names
are separated by different access modifiers.  I was wondering if they
can be sorted alphabetically as well.  Right now, even if the
SORT_MEMBER_DOCS is YES, the brief descriptions appear in the order
in which the functions are declared in the header, *NOT* sorted...
It would be nice to have an option for sorting them.


-----Original Message-----
From: dox...@li...
[mailto:dox...@li...] On Behalf Of
Prikryl,Petr
Sent: Thursday, 13 September, 2001 03:35
To: Anthony Yuen; dox...@li...
Subject: RE: [Doxygen-users] Sorting member functions (bug?)

Try "doxygen -g" to generate Doxyfile with comments.
Then look for SORT_MEMBER_DOCS.

You can find the following:

# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen
# will sort the (detailed) documentation of file and class members
# alphabetically by member name. If set to NO the members will appear in
# declaration order.

SORT_MEMBER_DOCS       = YES

It works for me concerning the detailed descriptions.  On the other
hand,
the list of methods with brief descriptions (in the first part of a
documentation
page for a class) is not sorted.  I guess that it can be a bug.  Or is
it
intentional?

Thanks,
  Petr

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

[Doxygen-users] Bug: cannot use % and \c together

[Moshe K. <Kr...@Pa...>]

I cannot seem to make \c and % work together in any combination: that is to
render a work in fixed-proportion font and disable the link.
 
Anyone encountered this problem and found a solution?
 
<tt></tt> works for the fixed-proportion font part, but of course it's a
shlepp and makes the code more heavy and illegible than it is anyhow.
 
Moshe Kruger
Paradigm Geophysical

[Doxygen-users] Problems with member groups

[Raimund K. <rk...@or...>]

Hi Dimitri and all,

I havbe found one and, well, I guess a half, bugs with simple member
groups. One apparently is related to not using the \name command (that's
the half), the other one is a relatively serious LaTeX error.

I'll start with the latter, since there seems to be no good workaround
for this one.

Let's say I have a class Test coded and documented like this:

class Test 
{
public :
    /** Brief group description.
     *
     *  Second paragraph of group description.
     *
     *  \name something
     */
    /*@{*/
    int a;
    int b;
    /*@}*/
};

"a" and "b" are grouped together in the group "something", but the
"Public Attributes" part of the generated LaTeX file looks like this:

\subsection*{Public Attributes}
\begin{CompactItemize}
\end{CompactItemize}
\begin{Indent}{\bf something}\par
{\em Brief group description.

Second paragraph of group description.}\begin{CompactItemize}
\item 
int {\bf a}
\item 
int {\bf b}
\end{CompactItemize}
\end{Indent}

This generates a LaTeX error, because the CompactItemize environment in
lines 2 and 3 is empty. In general, LaTeX does not allow list
environments without a single \item.

The other problem arises when I don't include a \name command - this
actually is the case in several places of the project I am currently
working on: Some members are related to each other and therefore should
be grouped together; however, a group name seems superfluous. The result
is about the same in HTML and LaTeX output: The group structure appears
to get lost as well as the second documentation paragraph. Additionally,
the group description is not associated to "a" and "b", but just to "a".
E.g., the LaTeX output looks like this:

\section{Test  Class Reference}
\label{classTest}\index{Test@{Test}}
{\tt \#include $<$test.h$>$}

\subsection*{Public Attributes}
\begin{CompactItemize}
\end{CompactItemize}
{\bf }\par
\begin{CompactItemize}
\item 
int {\bf a}
\begin{CompactList}\small\item\em Brief group
description.\item\end{CompactList}\item 
int {\bf b}
\end{CompactItemize}



\subsection{Member Data Documentation}
\index{Test@{Test}!a@{a}}
\index{a@{a}!Test@{Test}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int
Test::a}\label{classTest_m0}


Brief group description.



Definition at line 9 of file test.h.\index{Test@{Test}!b@{b}}
\index{b@{b}!Test@{Test}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int
Test::b}\label{classTest_m1}




Definition at line 10 of file test.h.

The documentation for this class was generated from the following
file:\begin{CompactItemize}
\item 
{\bf test.h}\end{CompactItemize}


Just to make sure: I am using the latest CVS checkout.

Regards,
-- 
Raimund Klein <kl...@or...>
Orthogon GmbH, Hastedter Osterdeich 222, D-28207 Bremen

RE: [Doxygen-users] Sorting member functions (bug?)

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

Try "doxygen -g" to generate Doxyfile with comments.
Then look for SORT_MEMBER_DOCS.  

You can find the following:

# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen
# will sort the (detailed) documentation of file and class members
# alphabetically by member name. If set to NO the members will appear in
# declaration order.

SORT_MEMBER_DOCS       = YES

It works for me concerning the detailed descriptions.  On the other hand,
the list of methods with brief descriptions (in the first part of a
documentation
page for a class) is not sorted.  I guess that it can be a bug.  Or is it
intentional?

Thanks,
  Petr

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

> -----Original Message-----
> From:	Anthony Yuen [SMTP:an...@ac...]
> Sent:	Thursday, September 13, 2001 5:38 AM
> To:	dox...@li...
> Subject:	[Doxygen-users] Sorting member functions
> 
>  
> Hi, I just started using Doxygen, please bear with me.  I'd like
> to have the member functions of my C++ classes to be sorted
> alphabetically,
> section by section (i.e. public, protected, private are separately
> sorted).  Is
> there such an option in Doxygen?  I'm using 1.2.10.  Thanks for your help.
>  
>  

[Doxygen-users] Sorting member functions

[Anthony Y. <an...@ac...>]

 
Hi, I just started using Doxygen, please bear with me.  I'd like
to have the member functions of my C++ classes to be sorted
alphabetically,
section by section (i.e. public, protected, private are separately
sorted).  Is
there such an option in Doxygen?  I'm using 1.2.10.  Thanks for your
help.
 
 

[Doxygen-users] # linking command not working under \retval

[<dr...@ca...>]

Does anyone know why the # command to generate a link doesn't work under
\retval?

example :

#define I_WILL_GET_LINKED 0
#define I_WONT_GET_LINKED 1

/*!

  #I_WILL_GET_LINKED

   \param myParam1
      the following will be a generated link #I_WILL_GET_LINKED


   \retval #I_WONT_GET_LINKED
      an error occured
   \retval #I_WONT_GET_LINKED
      This link wont get generated

*/

Dimitri, could you fix this please?


Thx.

[Doxygen-users] typedef problem

[Rob D. <rd...@ce...>]

I am having problems with the HTML output generated from the code below.
Using doxygen-1.2.10 on WIN2000 the first typedef (allocFunc) comes out ok
but the second typedef(freeFunc) is mistakenly documented as a function.
If I remove CALLCONV from the typedefs then the output is ok.

This is a simplified example where CALLCONV is always __cdecl but in my real
project
CALLCONV will vary depending on the platform.



/** @file file.h */

/** @def CALLCONV __cdecl
*/
#define CALLCONV __cdecl

/**  @typedef void* (CALLCONV *allocFunc )( int size, void * const memRef );

   Prototype for the callback function which allocates memory.

Notes:

@param size    [Input]  Number of bytes to allocate.
@param memRef  [Input]  User reference parameter.

@return pointer to allocated memory

*/
typedef  void* (CALLCONV *allocFunc )(
    int size,
    void * const memRef
    );

/**  @typedef void* ( CALLCONV *freeFunc )( void *block, void * const memRef );

   Prototype for the callback function which frees memory.

Notes:

@param block   [Input/Output]  Block to free.
@param memRef  [Input]  User reference parameter.

@return nothing

*/
typedef  void (CALLCONV *freeFunc )(
    void *block,
    void * const memRef
    );

/** @struct MemCallbacks
 * Structure for memory callbacks
 */
struct MemCallbacks
{

    /** memory allocation callback */
    allocFunc malloc;

    /** memory de-allocation callback */
    freeFunc free;

    /** reference for memory callbacks */
    void * memRef;
} MemCallbacks;

/** @typedef struct MemCallbacks MemCallbacks
 * Structure for application callbacks
 */
typedef struct MemCallbacks MemCallbacks;

[Doxygen-users] Fwd: Documenting command lines options

[root <bob...@bo...>]

I tried to post this a few days ago, but did not see it on the mail list. 
Forgive me if this is a repeat post for everyoe else.


My project includes a shell like command line processor with commands in the
ususal unix command line format. eg.

command -a -bvalue

I'd like to document them using doxygen and incorporate them into the rest of
my docs. I have two questions.

Are there any options available for assisting in documenting such commands
something like the following

/*! \page command.html command description
\command command -a -bvalue
\param -a Does whatever -a does
\param -bvalue Does whatever -b value does

Long Description of command

\sa othercommand, yetanothercommand
*/

Secondly if I want a section to describe all these commands, one command per
page, I can create each page with the \page command but then each commands
page shows up in the related docs section. I'd prefer only the top level page
giving an overview fo the commands and links to the other pages to appear
there. Is this possible.

Thanks

Bob S.

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

Re: [Doxygen-users] Suggestion

[Roberto B. <ba...@cs...>]

Luigi Ballabio wrote:
> 
> Hi all (and especially Dimitri),
>         lately I have been writing a few general sections in my
> documentation---"general" meaning an overview of the problem addressed by
> the code as opposed to "non general" being the documentation of a single
> method/class---and I thought that it would be nice to have a command for
> references.
> 
> It could work like:
> /*! \page etc.
>      ...
>      As pointed out in
>      \cite (some_label?)
>      Doe J., "Gnats and Gnus", Journal of This and That 12, 2001
>      \endcite
>      gnats can be nastier than gnus at times.
>      ...
> */
> 
> This would cause the above block to appear in the documentation as
> 
>      As pointed out in [1], gnats can be nastier than gnus at times.
> 
> while a separate page (the list of references) would contain among others
> 
>      [1] Doe J., "Gnats and Gnus", Journal of This and That 12, 2001.
> 
> The [1] in the documentation would be a link to the appropriate entry in
> the list of references.
> 
> Would it be at least moderately easy to implement? Could it use BibTeX for
> LaTeX output? Does anyone like the idea? Suggestions? Rejections?

I think that this is a great idea and a feature (BibTeX support included)
that I would love to have.
All the best,

    Roberto

-- 
Roberto Bagnara
Computer Science Group
Department of Mathematics, University of Parma, Italy
http://www.cs.unipr.it/~bagnara/
mailto:ba...@cs...

[Doxygen-users] Updated XML patch

[Christian H. <ch...@po...>]

Attached is an updated XML bug fix patch. With these changes, I am now
able to generate XML-compliant documentation for both my small test
cases and my large applications and libraries. Previously, the tags
being generated were not balanced, and thus could not be parsed by
any XML parsers.

It shouldn't have disturbed any of the other doc generators, but I
haven't tested them all with this to be sure.

-- 
Christian Hammond         <>  The GNUpdate Project
ch...@po...  <>  http://www.gnupdate.org/

[Doxygen-users] \refitem keyword

[John S. <joh...@se...>]

Hi all,

Can anybody enlighten me as to what the \refitem keyword officially
does? Can't find a description for it in the doc, though the source for
the doc (commands.doc, config.doc) use it extensively.

Also, whilst playing around with config.doc, I've noticed that
  \refitem FOO FOO
produces an empty list item. Bug?

Cheers,

John

[Doxygen-users] Suggestion

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

Hi all (and especially Dimitri),
	lately I have been writing a few general sections in my 
documentation---"general" meaning an overview of the problem addressed by 
the code as opposed to "non general" being the documentation of a single 
method/class---and I thought that it would be nice to have a command for 
references.

It could work like:
/*! \page etc.
     ...
     As pointed out in
     \cite (some_label?)
     Doe J., "Gnats and Gnus", Journal of This and That 12, 2001
     \endcite
     gnats can be nastier than gnus at times.
     ...
*/

This would cause the above block to appear in the documentation as

     As pointed out in [1], gnats can be nastier than gnus at times.

while a separate page (the list of references) would contain among others

     [1] Doe J., "Gnats and Gnus", Journal of This and That 12, 2001.

The [1] in the documentation would be a link to the appropriate entry in 
the list of references.

Would it be at least moderately easy to implement? Could it use BibTeX for 
LaTeX output? Does anyone like the idea? Suggestions? Rejections?

Bye,
	Luigi