doxygen-users — List for users of doxygen

[Doxygen-users] RE: [Large] Algorithmics comments or comments inside body functio ns

[Putman, H. <Pu...@di...>]

In my experience developing software, the most important thing about comments is that you are forced to keep them up to date. The best way to keep them up to date is to keep them close to the code they describe. If a description of an algorithm is in the function body, then when the algorithm changes you would naturally change the comments.

I can tell you we have lots of code that has comment header for functions where the parameters, or function names are wrong because someone forgot to come back and change it after they did a cut and paste of a similar function.

The best thing about Doxygen is that it derives alot of its documentation right from the code itself, which is the only part of the code that is garanteed to be accurate.

There are different audiences for generated documentation. I think Doxygen is already set up to accommodate that by being able to do things like not extract documentation for static C functions. Comments in the function body would be like this -- targeted at the development team but not end users.

\return Cheers,

Harold

Re: [Doxygen-users] [Large] Algorithmics comments or comments ins ide body functions.

[Jose L. Z. <jlz...@ca...>]

El Mié 26 Sep 2001 11:40, escribiste:
> ...one more comment ;-)
>
> > OK. I think so. It's all right. But, when you have hurry up is very easy
> > forget the generic abtract comment but it's easy to write a little coment
> > near the for keyword, or near the if keyword or near the return keyword.
>
> I see.  You are not the only one to forget this.
> Often, the final form of the comment is known
> only after the final implementation.  In such case,
> I use \todo command, like here:
>
> /*! \brief This is brief description.
>
>   This is the abstract comment describing less briefly
>   the functionality.  But it is not finished!
>
> \todo Update the comment.
> */
> int f()
> {
>    return 42;  // i.e. solving the same problem in constant time ;-)
> }
>

	This is the first step to don't write the documentation ;-)
Regards

-- 
José Luis Zabalza
jlz...@ca...
Linux User 172551

Re: [Doxygen-users] [Large] Algorithmics comments or comments ins ide body functions.

[Jose L. Z. <jlz...@ca...>]

El Mié 26 Sep 2001 10:35, escribiste:
> Hi Jose and others,
>
> You have to type more characters, and (what is
> more important) you have to think about what you
> are expected to type.  You have to take care to
> get the good result.  Rather exagerating, you are
> writing another program in parallel.

	**** Yes **** this is the question. If doxigen scan inside the functions and 
recongize the keywords (for, if, while, switch) I don't need worry about the 
indentation.


>
>
> An algorithm is only a part of the solution.  

	OK. ¿ It is not importat to show it in documentation ?

>Data
> structures (also the dynamic ones) are another
> part. The cooperation between the parts of the
> application is also important.  When you are fixed
> to some algorithmic view at very early stage, you
> may loose the global view to the solution.

	OK. I agree. But ** also ** is important.
>
> The object oriented programming and design is the
> result of also such observations.  One should
> decompose the problem very carefully, not thinking
> about implementation details at the beginning.

	100 % OK But when you have problems any help is good.


> Each change in the abstract view may cause changes
> of those details.  

	OK but the "details comments" are just near the code. You need to be a beast 
to no correct the situation and comment the changes.

> In other words,
> you do NOT know ** how ** excactly it will be
> implemented, but you are somehow convinced that it
> is possible to implement it.  You must know
> ** what ** it should do.
>
	OK but when you have problems... You need see the code. And I don't want 
this.

> The ** how ** is not that much important here if
> you know that it is possible ** somehow **.

	are you sure ?
>
> > I think in a algorithm. After I encode this
> > algorithm. And if I have some time, I document the
> > program. This is wrong. Doxigen help me to write
> > the documentation near the code, so I write the
> > documentation at same time.
>
> I have observed many times that programmers
> (students in my case) often tend to explain their
> project in say "algorithmic way" like:
>
>   "If this holds, I do that.  Then if this is the
>    result, I do this..."
>
> It's because they think this way when implementing
> the solution.  They know ** what ** they are implementing.
> But for other people---and even for other programmers
> (students) who do not work on the same project---this kind
> of explanation brings too much details and do not
> give some global overview of the problem.  

	If you have documented ** what ** and ** how ** you don't need see ** how 
**. But if you have problems you need ** how **

	If you are a teacher, ask this questions to your students?

	What happen if you have a undocumented or insuficient documented code ?

	Result = Smoke in head by reading the code.

	
>
> Then, if you finally hide it, why do you want to
> generate it?  Only to work with "sources" through
> the documentation?

	Because the comments inside the functions are important * only * when I have 
problems and read the code is a waste time if the code are writed by a 
programmers team.


> >
> > OK ;-) I am a newbie.
>
> ;-) Don't take me wrong.  I am not your teacher,
> and you are not my student.  

	Why not? I like learn.

> We are absolutely equal
> here.  I am also learning by reading the ideas
> like yours.

	I am a experience programer and I find doxigen after write many code lines 
and many unlinked documents. I like doxygen. It is also I search.

Thank you very munch. It is very instructive.


-- 
José Luis Zabalza
jlz...@ca...
Linux User 172551

[Doxygen-users] newbie Q : can't compile doxygen-1.2.10

[PINSON F. FTRD/DMI/L. <fre...@rd...>]

Hi,=20
I have juste downloaded the doxygen-1.2.10 release (src for unix)
I tried to compile on a solairs 2.8 SparcStation, and here is what I =
got :

make[2]: Entering directory `/users/pinson/Outils/doxygen1.2.10/src'
CC -c -O2 -I../qtools -o ../objects/classdef.o classdef.cpp
"entry.h", line 220: Error: Identifier expected instead of "}".
1 Error(s) detected.
make[2]: *** [../objects/classdef.o] Error 1
make[2]: Leaving directory `/users/pinson/Outils/doxygen1.2.10/src'
make[1]: *** [all] Error 2
make[1]: Leaving directory `/users/pinson/Outils/doxygen1.2.10/src'



can you help me ?

regards,=20
Fr=E9d=E9rique Pinson
FTR&D
fre...@rd...

RE: [Doxygen-users] [Large] Algorithmics comments or comments ins ide body functions.

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

...one more comment ;-)

Jose Luis Zabalza wrote:
>
> Petr Prikryl wrote:
> >
> > [...] any function should be on a
> > bit higher level of abstraction [...]
> > for me it is much easier to
> > sketch the idea more roughly in the comment
> > outside the body.
>
> OK. I think so. It's all right. But, when you have hurry up is very easy 
> forget the generic abtract comment but it's easy to write a little coment 
> near the for keyword, or near the if keyword or near the return keyword.

I see.  You are not the only one to forget this.
Often, the final form of the comment is known 
only after the final implementation.  In such case,
I use \todo command, like here:

/*! \brief This is brief description.
  
  This is the abstract comment describing less briefly
  the functionality.  But it is not finished!

\todo Update the comment.
*/
int f()
{
   return 42;  // i.e. solving the same problem in constant time ;-)
}

HTH,
  Petr

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

RE: [Doxygen-users] [Large] Algorithmics comments or comments ins ide body functions.

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

Hi Jose and others,

Jose Luis Zabalza wrote:
>
> Petr Prikryl wrote:
> >
> > Jose Luis Zabalza wrote:
> > > I come back again about the idea of ** what ** do
> > > a function or ** how ** do the function his work.
> > > I believe is important the documentation show two
> > > things.
> >
> > On the other hand, any function should be on a
> > bit higher level of abstraction than the things
> > inside the body. [...] While
> > you may want to extract some points about how the
> > function works, for me it is much easier to
> > sketch the idea more roughly in the comment
> > outside the body.
> 
> OK. I think so. It's all right. But, when you have
> hurry up is very easy forget the generic abtract
> comment but it's easy to write a little coment
> near the for keyword, or near the if keyword or
> near the return keyword.

I think that this is quite important point.  My
view is that you should never hurry so much ;-)
Otherwise, it finally takes more time than going a
bit more slowly.  

One more notice here; when I wrote about higher
level of abstraction, I was not thinking only
about describing the existing commands in human
language.  I meant also to decrease "the complexity
of the description" by, say, collapsing loops and
branches, etc.

See other comments below.

> > If you want even more details, you can use
> >   INLINE_SOURCES = YES
> >   SOURCE_BROWSER = YES
> > in your Doxyfile.
> 
> Yes, but this is very noisely, it is more descriptive :
>         
>     - This.
>     - If this
>         - this.

One problem is that when polishing the approach,
you may finish with another (description) language
with your own syntax -- i.e. something that
increase the complexity of your work.  Look at your
indentation notation, for example.  

    # A algorithmic comment has the format :
    #
    #           // <(.*)> Algorithmic comment.
    #           // comment continuation.
    #              until a no init comment line.
    #
    # Where (.*) can to be :
    #
    #    <>   : Algorithmic comment init.
    #    <+>  : Algorithmic comment init indent +1 position.
    #    <->  : Algorithmic comment init indent -1 position.
    #    <-n> : Algorithmic comment init indent -n position.


You have to type more characters, and (what is
more important) you have to think about what you
are expected to type.  You have to take care to
get the good result.  Rather exagerating, you are
writing another program in parallel.

> When you design a program. What is the first think
> you do ?

I think about "the problem". ;-)

An algorithm is only a part of the solution.  Data
structures (also the dynamic ones) are another
part. The cooperation between the parts of the
application is also important.  When you are fixed
to some algorithmic view at very early stage, you
may loose the global view to the solution.

The object oriented programming and design is the
result of also such observations.  One should
decompose the problem very carefully, not thinking
about implementation details at the beginning.
Each change in the abstract view may cause changes
of those details.  If you put too much work into
designing the details, you may feel sorry later to
throw it away, and this, in turn, may break the
search for better solution.

One should start to decompose the problem from the
top to the bottom, hierarchically (once known as
top-down design, but mainly from the algorithmic
point of view).  One should preserve clean
interfaces between the parts (no dirty dependences
on some internals of the solution) -- I am
thinking about the abstract view here, not about
typing the source.

One should continue to decompose until you reach
some level where you know that the part is
implementable, self-contained.  In other words,
you do NOT know ** how ** excactly it will be
implemented, but you are somehow convinced that it
is possible to implement it.  You must know 
** what ** it should do.

... and this is the key point.  This should be
documented.  This gives you some some global view
of the problem.  And this should also be the case
when documenting functions, especially the member
functions (i.e. object or class methods).  
The ** how ** is not that much important here if
you know that it is possible ** somehow **.

> I think in a algorithm. After I encode this
> algorithm. And if I have some time, I document the
> program. This is wrong. Doxigen help me to write
> the documentation near the code, so I write the
> documentation at same time.

I have observed many times that programmers
(students in my case) often tend to explain their
project in say "algorithmic way" like:
  
  "If this holds, I do that.  Then if this is the
   result, I do this..."

It's because they think this way when implementing
the solution.  They know ** what ** they are implementing.
But for other people---and even for other programmers 
(students) who do not work on the same project---this kind
of explanation brings too much details and do not
give some global overview of the problem.  My
personal experience also is that after 2 or so
months (doing other things) you will be in a
position of "the other" person.  You will look at
the code that you wrote and you will try to
understand "Why is this done this way?".

In my opinion, writing good comments inside
function body is necessary to avoid such problems in
future.  But the question is whether you want to
extract them to the documentation.  Usually, you
need the comments inside the function body only if
you are really interested in understanding
details.  Probably, you are going to modify the
function.  Probably, you do it when you are
programming, looking inside sources.  It is
unlikely that you will want to do it through 
looking at the generated documentation.

The documentation must be much more brief
and somehow much different.  We should 
take advantage of the human ability to
understand also rather not mathematically-precise
descriptions.  The long, machine-oriented (or
mathematically accurate) descriptions are not
always better for humans.

When you extract the steps from the function body,
it is likely that the result will look very machine
oriented.  It will never be one sentence that will
describe the problem being solved.

> > Once your project and documentation gets bigger,
> > you will appreciate other features than digging
> > out as much details as possible.  The opposite
> > may be desired.  If the printed documentation
> > would have 2000 pages, nobody would ever read and
> > study it.  
> 
> OK. It is posible, hide or show algorithm coments.

Then, if you finally hide it, why do you want to
generate it?  Only to work with "sources" through
the documentation?

> > I went through the
> > same stage as you are going through now -- so I
> > think that I can speak about having such
> > experience.
> 
> OK ;-) I am a newbie.

;-) Don't take me wrong.  I am not your teacher,
and you are not my student.  We are absolutely equal
here.  I am also learning by reading the ideas
like yours.

Regards,
  Petr

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

[Doxygen-users] RE: [Large] Algorithmics comments or comments inside body functio ns.

[Putman, H. <Pu...@di...>]

I like the idea of commenting in the function body.

I actually tried putting 'special' comments in my function bodies hoping they would become part of the detailed description for the function. I think that would be logical. I think it would be most natural to add any indentation by hand using HTML tags. This would save having to learn a new set of tags for body comments.

 void funcion(void)
#   {
#       int i;
#
#   /// Increment the global variable a
#
#       a++;
#
#   /// Printing the message
#   /// the message is "Sayonara baby"
#
#       PrintMessage("Sayonara baby");
#
#   // It can be normal comments
#
#   /// For all componets in the array
#       for(i=0;i<a;i++)
#       { /// <ul> 
#           /// <li> print the component message
#           ArrayComponet[i].PrintMessage();
#
#           /// <li> For all component lines
#           while(ArrayComponent[i].NumLines())
#           { /// <ul>
#               /// <li> Get the line
#               CLine a=ArrayComponent[i].GetLine()
#               /// <li> Printing
#               a.Print();
#               /// <li> Deleting
#               a.Delete();
#           } /// </ul>
#       }// </ul>
#
#   /// Deleting the Array
#   ArrayComponent.Delete();
#
#   }


The configuration file could control whether these body comments were extracted since you might not want that included in your public documentation.

@return Cheers

Harold Putman

Re: [Doxygen-users] Warning: no matching class member found for class member found fo r ...

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

On Mon, Sep 24, 2001 at 11:29:29AM -0700, Osburn, Jim (jios) wrote:
> C:/home/jios/darwiz/nedit.h:87 Warning: no matching class member found for 
>   DARNumberEdit::GetEnglishText
> Possible candidates:
>   void GetEnglishText(CString &str)
> 
> what do i need to put in the header and the implementation file?

Nothing special. These kind of warnings are typically the result of
a parsing problem within doxygen. There are many possible causes. Some
typical ones:

1) the declaration and definition of arguments do not match syntactically
   (e.g. both are integers but one is a typedef or macro).
2) doxygen is confused by a function macro in the class (typical for
   boiler-plate code in MFC, ATL and the alike).

If you think doxygen should have been able to find a match please send me a
small code snipet containing the problem.

Regards,
  Dimitri

Re: [Doxygen-users] [Large] Algorithmics comments or comments ins ide body functions.

[Jose L. Z. <jlz...@ca...>]

El Mar 25 Sep 2001 13:56, escribiste:
> Hi Jose and others,
>
> Jose Luis Zabalza wrote:
> > I come back again about the idea of ** what ** do
> > a function or ** how ** do the function his work.
> > I believe is important the documentation show two
> > things.
>
> On the other hand, any function should be on a
> bit higher level of abstraction than the things
> inside the body.  Because of this, the comment
> for the whole function (member function) should
> be more abstract.  My experience is that you get
> less when you dig-out too much details.  While
> you may want to extract some points about how the
> function works, for me it is much easier to
> sketch the idea more roughly in the comment
> outside the body.
>
	OK. I think so. It's all right. But, when you have hurry up is very easy 
forget the generic abtract comment but it's easy to write a little coment 
near the for keyword, or near the if keyword or near the return keyword.


> If you want even more details, you can use
>   INLINE_SOURCES = YES
>   SOURCE_BROWSER = YES
> in your Doxyfile.

	Yes, but this is very noisely, it is more descriptive :
	
	- This.
	- If this
		- this.
	
	When you design a program. What is the first think you do ?

	I think in a algorithm. After I encode this algorithm. And if I have some 
time, I document the program. This is wrong. Doxigen help me to write the 
documentation near the code, so I write the documentation at same time.

>
> Once your project and documentation gets bigger,
> you will appreciate other features than digging
> out as much details as possible.  The opposite
> may be desired.  If the printed documentation
> would have 2000 pages, nobody would ever read and
> study it.  

	OK. It is posible, hide or show algorithm coments.


> I went through the
> same stage as you are going through now -- so I
> think that I can speak about having such
> experience.)

	OK ;-) I am a newbie.

>
> This is just my opinion.  The decision to accept
> it or not is yours.

	Thanks for your opinion. It is very interesting.

Regards
	
-- 
José Luis Zabalza
jlz...@ca...
Linux User 172551

RE: [Doxygen-users] [Large] Algorithmics comments or comments ins ide body functions.

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

Hi Jose and others,

Jose Luis Zabalza wrote:
>
> I come back again about the idea of ** what ** do
> a function or ** how ** do the function his work.
> I believe is important the documentation show two
> things.
> 
> Doxigen is wonderful but not scan inside the
> function and I believe that inside the function
> must be the comments that say ** how ** the
> function work.
> [...]

Just to add my opinion.  I tend to put quite
descriptive blocks of comments into the function
bodies.  I feel that it is the more important the
larger the project is.  It's because after a
while you do not know what you wrote earlier, and
it is much easier to remind the functionality by
reading good, human-readable comments that by
reexamining the commands.

On the other hand, any function should be on a
bit higher level of abstraction than the things
inside the body.  Because of this, the comment
for the whole function (member function) should
be more abstract.  My experience is that you get
less when you dig-out too much details.  While
you may want to extract some points about how the
function works, for me it is much easier to
sketch the idea more roughly in the comment
outside the body.

If you want even more details, you can use
  INLINE_SOURCES = YES 
  SOURCE_BROWSER = YES
in your Doxyfile.

In my opinion, it is much better to have some
global, more abstract view of the problem, and to
be able to go to details (if needed) quickly --
via automatically generated HTML links, for
example. (Doxygen is fairly good in it.)

Once your project and documentation gets bigger,
you will appreciate other features than digging
out as much details as possible.  The opposite
may be desired.  If the printed documentation
would have 2000 pages, nobody would ever read and
study it.  Then you will quickly start to switch
off some types of diagrams and some levels of
details.  Then the debate about in-body comments
starts to be rather academic.  (I once asked for
something similar just because it came to my mind
that it would be wonderful; I went through the
same stage as you are going through now -- so I
think that I can speak about having such
experience.)

Earlier, I worked as a university teacher (CS,
programming, OS, etc.).  I have always taught
students to write good comments.  It should be as
important and done so automatically as breathing.
One should learn typing by 10 fingers and write
down the ideas and human-readable explanantions
to comment blocks as soon as possible.  (You will
hardly do it better later, if ever.) When writing
such a comment block, you should be as fluent in
thinking and writing as if you were thinking and
speaking to someone (well, the speed is not that
important).  Adding some markup may break this
activity (you have to concentrate on syntax).

When writing Doxygen comments, it is another
matter.  You write them systematically (like
\brief, \param, \return, \note, \bug, \todo,
\sa,...) because you know that they can be
usefully processed -- much more usefully than the
points extracted for the body of a function.

This is just my opinion.  The decision to accept
it or not is yours.

With regards,
  Petr

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

[Doxygen-users] Problem with a simple C code

[dcoeurjo <dco...@di...>]

Hi All,

   I'm a complete Doxygen Beginner and I'm interesed in documenting classical C files.
I'd like to know how to have the same header function list in the File Reference web pages as for C++ code ? 

Thanks in advance,

Regards,

David.

-- 
------------------------------
David Coeurjolly
Doctorant
Universite Lumiere Lyon2
Laboratoire ERIC
5, avenue Pierre-Mendes-France
69676 Bron CEDEX
Tel labo : 04.78.77.43.77
dco...@er...
------------------------------

[Doxygen-users] Doxygen comments syntax highlighting

[Philippe L. <Ph...@gm...>]

Hello.

For your information, thanks to Steve Lhomme efforts, the SciTE editor, and
more precisely the Scintilla text editor component (version 1.40), is now
able to highlight Doxygen comment keywords in C, C++ and Java code.

See it at www.Scintilla.org, it is a great editor in all cases, and open
source too :-)

Regards.

-- 
--._.·´¯`·._.·´¯`·._.·´¯`·._.·´¯`·._.·´¯`·._.·´¯`·._.--
Philippe Lhoste (Paris -- France)
Professional programmer and amateur artist
http://jove.prohosting.com/~philho/
--´¯`·._.·´¯`·._.·´¯`·._.·´¯`·._.·´¯`·._.·´¯`·._.·´¯`--

Sent through GMX FreeMail - http://www.gmx.net

[Doxygen-users] [Large] Algorithmics comments or comments inside body functions.

[Jose L. Z. <jlz...@ca...>]

Hi all

I come back again about the idea of ** what ** do a function or ** how ** do 
the function his work. I believe is important the documentation show two 
things.

Doxigen is wonderful but not scan inside the function and I believe that 
inside the function must be the comments that say ** how ** the function work.

But Doxigen is wonderful and can filtering the files before processing. OK. I 
writed a dirty perl script filter to scan and extract the comments and put in 
special comment nearest. One example.

# This dirty perl script extract "Algorithmic comments" from the function's 
# body and they are put inside
# nearest special comment /** ... */
#
# A algorithmic comment has the format :
#
#           // <(.*)> Algorithmic comment.
#           // comment continuation.
#              until a no init comment line.
#
# Where (.*) can to be :
#
#    <>   : Algorithmic comment init.
#    <+>  : Algorithmic comment init indent +1 position.
#    <->  : Algorithmic comment init indent -1 position.
#    <-n> : Algorithmic comment init indent -n position.
#
# EXAMPLE :
#
#   /**
#    This is a little file example
#   */
#
#   /**
#    * @brief : This function do something
#    *
#    * You can put in this place some comment.
#    *
#    */
#   void funcion(void)
#   {
#       int i;
#
#   // <> Increment the global variable a
#
#       a++;
#
#   // <> Printing the message
#   // the message is "Sayonara baby"
#
#       PrintMessage("Sayonara baby");
#
#   // It can be normal comments
#
#   // <> For all componets in the array
#       for(i=0;i<a;i++)
#       { // <+>
#           // <> print the component message
#           ArrayComponet[i].PrintMessage();
#
#           // <> For all component lines
#           while(ArrayComponent[i].NumLines())
#           { // <+>
#               // <> Get the line
#               CLine a=ArrayComponent[i].GetLine()
#               // <> Printing
#               a.Print();
#               // <> Deleting
#               a.Delete();
#           } // <->
#       }// <->
#
#   // <> Deleting the Array
#   ArrayComponent.Delete();
#
#   }
#
# THE OUTPUT
#
#   /**
#    This is a little file example
#   */
#
#   /**
#    * @brief : This function do something
#    *
#    * You can put in this place some comment.
#<H3>Algorithm</H3>
#<UL>
#  <LI> Increment the global variable a
#  <LI> Printing the message
#       the message is "Sayonara baby"
#  <LI> For all componets in the array
#  <UL>
#     <LI> print the component message
#     <LI> For all component lines
#     <UL>
#        <LI> Get the line
#        <LI> Printing
#        <LI> Deleting
#     </UL>
#  </UL>
#  <LI> Deleting the Array
#</UL>
#    */
#   void funcion(void)
#   {
#       int i;
#
#
#       a++;
#
#
#       PrintMessage("Sayonara baby");
#
#   // It can be normal comments
#
#       for(i=0;i<a;i++)
#       {
#           ArrayComponet[i].PrintMessage();
#           while(ArrayComponent[i].NumLines())
#           {
#               CLine a=ArrayComponent[i].GetLine()
#               a.Print();
#               a.Delete();
#           }
#       }
#
#   ArrayComponent.Delete();
#   }
#

This is enough for my but It should be wonderful that Doxigen be able scan 
inside body functions and it be able recognize special comments before 
keywords (for, if, while ...) and indent automaticaly inside the keywords 
body or a algorithm graphic about ** how ** the function work.

It is only a idea.

Bye

P.D. I can send to you the script or put it in some ftp server but it is very 
simple.
-- 
José Luis Zabalza
jlz...@ca...
Linux User 172551

[Doxygen-users] Rodney Schuler/EIC/ING-FSI-NA is out of the office.

[<Rod...@in...>]

I will be out of the office starting  2001-09-24 and will not return until
2001-09-28.

I will try to check my email at least once a day.

[Doxygen-users] Tag files - Usage example

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

Hi All,

I am having problems using the tag files functionality.

I have a project which sources information from several libraries, all
which have there own Doxygen config file + code comments (All built by
developers other than me). My problem is that, although I can pick up
there tag files correctly,  the resulting html has no references to
any of the doco in the libraries.

The example outlined in section 9 of the User Manual does not seem to help.

Any idea's on what I maybe doing wrong.

Would someone have a simple example they could Email me ?

Thanks inadvance.

Regards,

Steve Walker.

Re: [Doxygen-users] Doxygen-1.2.10-20010923 in CVS

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

Using the # command under  \retval still doesn't create a link in
1.2.10-20010923.
Anyone knows if there's plans to fix it?



example :


#define BUFFER_TOO_SMALL -1

/*!
*
* \retval #BUFFER_TOO_SMALL the buffer supplied was too small to receive
the output.
*
*/
int example(int asdf, char *out_buffer){
...
}


Thx.

Denis Ricard
IBM Canada Software Development Lab,  4D-638


Dimitri van Heesch <di...@st...>@lists.sourceforge.net on 09/23/2001
01:35:27 PM

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

Sent by:  dox...@li...


To:   dox...@li...
cc:
Subject:  [Doxygen-users] Doxygen-1.2.10-20010923 in CVS


Hi,

Here's the changelog since last release:
----------------------------------------------------------
+ CHG: Changed the look of the various indices (file/class/namespace/...)
       in the HTML output.
+ BUG: Fixed crash bug when filtering CR+LF's from input.
+ BUG: Fixed a number of XML output bugs (thanks to Christian Hammond).
+ BUG: Fixed bug parsing character literals.
+ BUG: Fixed bug in RTF output (bracket mismatch).
+ BUG: Inializer of the last enum value of an enum did not always appear.
+ BUG: Dots were removed from return types in Java.
+ BUG: In some cases a broken "More..." link was generated after
       a brief class description.
+ BUG: Text of a section title containing was truncated if it contained an
       asterix.
----------------------------------------------------------
Enjoy,
  Dimitri

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

[Doxygen-users] Warning: no matching class member found for class member found fo r ...

[Osburn, J. (jios) <ji...@ch...>]

C:/home/jios/darwiz/nedit.h:87 Warning: no matching class member found for 
  DARNumberEdit::GetEnglishText
Possible candidates:
  void GetEnglishText(CString &str)

what do i need to put in the header and the implementation file?

jim

[Doxygen-users] Linking external doco/component library doco

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

 Hi All,
 
 Sorry for yet another basic question !
 
 I have the following directory struct:
 
 +-testprj                       /* Main Project */
         +-html
         |
         +-wdog                  /* Component library #1 */
         |       +-html
         |
         +-support               /* Component library #2 */
                 +-html
 
 sort of as per the Example in Section 9 of the manual (V-1.2.10)
 
 1/ The source files (*.c & *.h) plus the configuration file for Doxygen
    are in each of the "testprj", "wdog" & "support" dirs.
 
 2/ I run Doxygen in each of the subdirs, result being a wdog.tag and
    support.tag in their dirs respectively.
 
 3/ I run Doxygen in the "testprj" dir, supplying the tag file locations
    for the wdog and support components/libraries.
 
 4/ I change to the "testprj/html" dir and run installdox as instructed
 
 5/ I load the testprj/html/index.html file into my browser.
 
 My problems are:
 
 1/ In the "File List" link, I do NOT find and reference to the components
    in either the "wdog" or "support" dirs.
 
 2/ In fact I find NO references to the subdirs functionality on any page in
    the testprj/html dir.
 
 Where may I be going wrong ?
 
 I have attached(in zip file) a copy of my config files for each dir.
 
 testprj.cfg
 wdog.cfg
 support.cfg

 
 Regards,
 
 Steve Walker.

[Doxygen-users] Linking external doco/component library doco

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

Hi All,

Sorry for yet another basic question !


I have the following directory struct:


+-testprj			/* Main Project */
	+-html
	|
	+-wdog			/* Component library #1 */
	|	+-html
	|	
	+-support		/* Component library #2 */
		+-html


sort of as per the Example in Section 9 of the manual (V-1.2.10)


1/ The source files (*.c & *.h) plus the configuration file for Doxygen
   are in each of the "testprj", "wdog" & "support" dirs.

2/ I run Doxygen in each of the subdirs, result being a wdog.tag and 
   support.tag in their dirs respectively.

3/ I run Doxygen in the "testprj" dir, supplying the tag file locations
   for the wdog and support components/libraries.

4/ I change to the "testprj/html" dir and run installdox as instructed

5/ I load the testprj/html/index.html file into my browser.


My problems are:

1/ In the "File List" link, I do NOT find and reference to the components
   in either the "wdog" or "support" dirs.

2/ In fact I find NO references to the subdirs functionality on any page in
   the testprj/html dir.

Where may I be going wrong ?

I have attached a copy of my config files for each dir.

testprj.cfg
wdog.cfg
support.cfg

Regards,

Steve Walker.

[Doxygen-users] Doxygen-1.2.10-20010923 in CVS

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

Hi,

Here's the changelog since last release:
----------------------------------------------------------
+ CHG: Changed the look of the various indices (file/class/namespace/...)
       in the HTML output.
+ BUG: Fixed crash bug when filtering CR+LF's from input.
+ BUG: Fixed a number of XML output bugs (thanks to Christian Hammond).
+ BUG: Fixed bug parsing character literals.
+ BUG: Fixed bug in RTF output (bracket mismatch).
+ BUG: Inializer of the last enum value of an enum did not always appear.
+ BUG: Dots were removed from return types in Java.
+ BUG: In some cases a broken "More..." link was generated after
       a brief class description.
+ BUG: Text of a section title containing was truncated if it contained an
       asterix.
----------------------------------------------------------
Enjoy,
  Dimitri

Re: [Doxygen-users] Help? 1.2.10, member grouping, and template classes

[Phil E. <ped...@di...>]

On Sat, Sep 22, 2001 at 11:53:16AM +0200, Dimitri van Heesch wrote:
> > The namespace is documented; other members show up okay.  But here, only
> > unary_function is considered documented.  Nothing about binary_function
> > shows up at all.  The config file has DISTRIBUTE_GROUP_DOC set to YES.
> 
> Member grouping only works for members (of classes, namespaces or files), 
> not for classes, namespaces or files themselves.

Oh.  I was thinking that these counted as "members of files," but now I'm
assuming that members of files refers to static variables and the like.

I guess I'll try the other kind of grouping.  Thanks!

Phil

-- 
"You have to wonder what kind of life you have when your list of personal
rules begins with, '#3:  No drowning in your own mucus,' and '#4:  Don't
ask what happened to rules 1 and 2.'"

Re: [Doxygen-users] Help? 1.2.10, member grouping, and template classes

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

On Wed, Sep 19, 2001 at 03:34:00PM -0400, Phil Edwards wrote:
> I'm using Doxygen 1.2.10 to generate HTML for GNU's libstdc++.  Using member
> groups to group/distribute documentation works fine with global functions,
> like
> 
>     //@{
>     /** These are replaceable signatures:
>      *  blah blah blah
>     */
>     void *operator new(std::size_t) throw (std::bad_alloc);
>     void *operator new[](std::size_t) throw (std::bad_alloc);
>     void operator delete(void *) throw();
>     .....
>     //@}
> 
> But not with templates.  Trying things like
> 
>     namespace std
>     {
>       /** General documentation about both of these classes.
>       */
>       //@{
>       template <class _Arg, class _Result>
>       struct unary_function {
>         ...
>       };
>       template <class _Arg1, class _Arg2, class _Result>
>       struct binary_function {
>         ...
>       };      
>       //@}
> 
> The namespace is documented; other members show up okay.  But here, only
> unary_function is considered documented.  Nothing about binary_function
> shows up at all.  The config file has DISTRIBUTE_GROUP_DOC set to YES.
> 
> Am I missing anything?  (Please Cc me, I'm not subscribed.)

Member grouping only works for members (of classes, namespaces or files), 
not for classes, namespaces or files themselves.

Regards,
  Dimitri

[Doxygen-users] Formatting & excluding link

[Dirk M. <dm...@ro...>]

Hi:

I'm working with Doxygen 1.2.10 on Win2k, downloaded from the Doxygen
website.

I'm trying to get a function name to be both unlinked and in constant-width
font.  Documentation like:

/*!
 * Compares two Dog objects.  Contrast with the \c %operator==() for
comparing
 * Cats, which always returns false (because everyone knows you can't get
two
 * Cats into the same function at the same time.)
 */

  bool operator==(const Dog& first, const Dog& second) {...}; 


Produces this HTML:

<p>
Compares two Dog objects. Contrast with the <code>%operator==()</code> for
comparing Cats, which always returns false (because everyone knows you can't
get two Cats into the same function at the same time.)

(Including the full function signature for the function being discussed does
give me the correct link. Leaving the function in default font gives me an
unlinked function without the leading %. So, I've got options for dealing
with this, just not the one I prefer.)

Is there a way to convince Doxygen to exclude a link, present the function
in constant-width font, *and* remove the leading %?

Thanks,

Dirk
dm...@ro...

[Doxygen-users] Re: Help? 1.2.10, member grouping, and template classes

[Phil E. <ped...@di...>]

I forgot to add that in the problem case,

>       /** General documentation about both of these classes.
>       */
>       //@{
>       template <class _Arg, class _Result>
>       struct unary_function {
>         ...
>       };
>       template <class _Arg1, class _Arg2, class _Result>
>       struct binary_function {
>         ...
>       };      
>       //@}

it does not matter whether the //@{ follows the comment block as above,
or preceeds it.  Either way, only the first class is listed in the output.


Phil

-- 
Would I had phrases that are not known, utterances that are strange, in
new language that has not been used, free from repetition, not an utterance
which has grown stale, which men of old have spoken.
                                     - anonymous Egyptian scribe, c.1700 BC

[Doxygen-users] Help? 1.2.10, member grouping, and template classes

[Phil E. <ped...@di...>]

I'm using Doxygen 1.2.10 to generate HTML for GNU's libstdc++.  Using member
groups to group/distribute documentation works fine with global functions,
like

    //@{
    /** These are replaceable signatures:
     *  blah blah blah
    */
    void *operator new(std::size_t) throw (std::bad_alloc);
    void *operator new[](std::size_t) throw (std::bad_alloc);
    void operator delete(void *) throw();
    .....
    //@}

But not with templates.  Trying things like

    namespace std
    {
      /** General documentation about both of these classes.
      */
      //@{
      template <class _Arg, class _Result>
      struct unary_function {
        ...
      };
      template <class _Arg1, class _Arg2, class _Result>
      struct binary_function {
        ...
      };      
      //@}

The namespace is documented; other members show up okay.  But here, only
unary_function is considered documented.  Nothing about binary_function
shows up at all.  The config file has DISTRIBUTE_GROUP_DOC set to YES.

Am I missing anything?  (Please Cc me, I'm not subscribed.)


Thanks,
Phil

-- 
Would I had phrases that are not known, utterances that are strange, in
new language that has not been used, free from repetition, not an utterance
which has grown stale, which men of old have spoken.
                                     - anonymous Egyptian scribe, c.1700 BC