doxygen-develop — List for discussing new features, submitting patches, etc.

[Doxygen-develop] Doxygen and C++/.NET

[Jason M. <jm...@cs...>]

Two few related questions:

- Have anyone used doxygen with Managed C++ (.NET)? If so, are there any 
filters available to handle managed C++ keywords, such as __interface?

- Will there ever be support for the soon to be available C++/CLI?

Thanks,
Jason

Re: [Doxygen-develop] Aliases

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

On Mon, Feb 07, 2005 at 10:36:28AM -0600, Randall, Larry wrote:
> I have noticed that 1.3.8 and 1.4.x ignore the \n in an alias and start
> on the same line as previous output.  Example:
> 
>  "rev = Revision \n" \
>  "syn = Syntax \n" \
> 
> I have even tried:
>  "lib = \n Library \n"
> 
> This produces:
> 	Library ImageConversion.lib 
> 
> When \lib and \syn are "stacked", these produce:
> 	Library ImageConversion.lib Syntax Test of Syntax and code
> style:  static CBufferCopyListener* NewL(const RThread* aSubThread)  
> 
> Previous output was: 
> 
> 	Library (bolded)
> 		ImageConversion.lib 
> 
> 	Syntax  (bolded)
> 		Test of Syntax and code style:  static
> CBufferCopyListener* NewL(const RThread* aSubThread)

To me this sounds like you want to define the aliases like this:
ALIASES                = "syn=\par Syntax:\n" \
                         "lib=\par Library:\n"

Regards,
  Dimitri

[Doxygen-develop] Aliases

[Randall, L. <l-r...@ti...>]

I have noticed that 1.3.8 and 1.4.x ignore the \n in an alias and start
on the same line as previous output.  Example:

 "rev =3D Revision \n" \
 "syn =3D Syntax \n" \

I have even tried:
 "lib =3D \n Library \n"

This produces:
	Library ImageConversion.lib=20

When \lib and \syn are "stacked", these produce:
	Library ImageConversion.lib Syntax Test of Syntax and code
style:  static CBufferCopyListener* NewL(const RThread* aSubThread) =20

Previous output was:=20

	Library (bolded)
		ImageConversion.lib=20

	Syntax  (bolded)
		Test of Syntax and code style:  static
CBufferCopyListener* NewL(const RThread* aSubThread)
 =20

Regards,=20
Larry Randall =20
OMAP(tm) Program Facilitation Office=20
 =20

[Doxygen-develop] \verbinclude does not include verbatim

[Marcel L. <lo...@as...>]

Hi,

I already submitted this to Bugzilla (
http://bugzilla.gnome.org/show_bug.cgi?id=165793 ), but the list of
unconfirmed and new items in Bugzilla it quite long; which makes me
wonder whether I should submit this bug here as well. Anyway, here is
comes.

The command \verbinclude does not include a file verbatim when source
file 
filtering is turned on. The attached files demonstrate this. The
doxybug.doc 
file describes the bug; the doxybug.h file is a standard "legacy"
header file 
which is filtered by the input filter slash2spanning.pl (a modified
version of 
the one that is on the Doxygen site).

Run doxygen using the supplied configuration file doxybug.cfg and look
at the 
generated HTML files.

It seems this bug was introduced in version 1.3, because 1.2.18 does
not show this behaviour.

I've been digging in the sources a bit -- pretty well organized -- and
probably
found the culprit in docparser.cpp, function readTextFileByName().

The following patch probably solves this bug -- note: this patch is for
version 1.4.1 of Doxygen

--- docparser.cpp~	2005-01-03 20:17:52.000000000 +0100
+++ docparser.cpp	2005-01-31 13:42:30.000000000 +0100
@@ -1332,7 +1332,7 @@
   FileDef *fd;
   if ((fd=findFileDef(Doxygen::exampleNameDict,file,ambig)))
   {
-    text =
fileToString(fd->absFilePath(),Config_getBool("FILTER_SOURCE_FILES"));
+    text = fileToString(fd->absFilePath());
   }
   else if (ambig)
   {


Regards,

	Marcel Loose.

Re: [Doxygen-develop] Man pages for library functions

[Chris C. <do...@ke...>]

On Wed, Feb 02, 2005 at 08:32:57PM +0100, Asmund Ostvold wrote:

>     What I want is two man-page (files) foo.3 and bar.3 not making a
>     single man-page. Maybe with the possibility to say what .h file it
>     is defined in.
> 
> How difficult do you think this would be to implement?  If it is not
> too difficult I am more then willing to contribute this functionality
> to the Doxygen frame work.
> 
> Is there any interest for this or is it only me that needs this?

I would be interested.  Nice to see that I'm not the only one still
doing man pages...

I'm not sure if this will make it to the Doxygen list, since SourceForge
hates my domain, which is why I'm copying to you directly.

Chris C

[Doxygen-develop] Man pages for library functions

[Asmund O. <as...@ti...>]

I posted a message on the user list asking if it was possible to get
separate man-page for each function(public) that a library offers.  I
did not get a answer. Does this functionality exist in Doxygen?

    Here is an example to show what I ma interested in doing.  His is
    a c file that implements some public functions for the API:
    
    In file ffff.c;
    -------
    /*! function foo do some thing
     * \param a Contains something
     * \param b Contains something else
     * \return something
     */
    int foo( int a, int b){
              
    }
    
    /*! function bar for something
     * \param a takes a size of something
     * \param b takes something
     * \return something
     */
    int bar( int a, int b ){
    //some code
    }
    ------
    
    What I want is two man-page (files) foo.3 and bar.3 not making a
    single man-page. Maybe with the possibility to say what .h file it
    is defined in.
    

How difficult do you think this would be to implement?  If it is not
too difficult I am more then willing to contribute this functionality
to the Doxygen frame work.

Is there any interest for this or is it only me that needs this?



Best regards 

Aasmund

[Doxygen-develop] several suggestions

[Ilya S. <ily...@MI...>]

Here is my "wish list" for Doxygen:

1. Support documenting "aspects" i.e. scattered code fragments that implement one functionality,
with the following simple changes:
    -- when the name of a module is mentioned in the comments (any comments -- including comments
    inside function code), in the doxygen-generated source listing make the module name 
    a hyperlink to the module documentation page
    -- on the module documentation page, add a list of source lines on which the module is mentioned,
    making each line a hyperlink to the corresponding line in the source listing generated by doxygen.

Then, in the doxygen-generated source listing, it's easy to find all code implementing a given functionality,
and it's easy to jump from a code chunk to all related chunks (via the module page).

2. Generate more automatic links from the source code listings -- any mention of a documented entity,
including in the comments other than the special comment blocks, can be linked to the documentation page for that entity
or to the definition of the entity in the source code.
And from the documentation page can link to the list of source lines on which the entity is used.

3. Allow placing named "anchors" in comments (in any comments -- not just in the special comment blocks), which can
then be referenced from the special comment blocks.  The reference generates a link to the source line containing
the anchor, in the doxygen-generated source listing.

4. Add brief descriptions to all generated pages -- e.g. on the "Data fields", the "Globals" pages etc. put the
brief description of each entity to the right of the name (truncated as needed).  Also when showing the parents
of a class as a DOT diagram, to the right of each parent class put a brief description.

5. Be able to document a directory -- right now the only way is to create a module and put all the files in the directory
into the module.  In Java, documenting packages takes care of this; but C doesn't have packages.

6. Be able to document "function outlines" -- inside function code, have stylized comments that can indicate outline levels;
when generating source listings, have a "function outline" page with two frames, one showing the outline items and the other
showing the source code; clicking on an outline item brings the corresponding source code line into view.

7. Incremental updating of documentation: only parse those files that have later modification dates than the corresponding
documentation files.  This can be implemented on top of the existing "tag file" functionality: have a tag file for each
source file, and re-generate only those tag files that are older than the corresponding source files.




   

Re: [Doxygen-develop] \interface tag - possible bug?

[James H. <jh...@ga...>]

Thanks for the replies.

When a description block is added the error disappears, but in the 
documentation Int still appears as a class, not an interface (i.e. it is 
listed in the class hierarchy and the heading for the documentation is 
'Int Class Reference').

So the \interface tag seems to be acting like an alias for \class. I was 
hoping that interfaces labelled with the \interface tag would be listed 
separately from the classes, ideally with a separate 'Interface List' in 
the Doxygen menu. Perhaps this is outside the scope of the current code.

Would I be right to guess that the intention is eventually to treat 
interfaces separately, but that listing them as classes is a measure to 
allow the tag to be used before it is fully implemented?

Many thanks,

James.


Dimitri van Heesch wrote:

>On Fri, 21 Jan 2005 08:50:47 -0400, Christian Baribeau
><chr...@am...> wrote:
>  
>
>>Allo James!
>> 
>>Just to further amplified your email message.
>> 
>>I ran the test case test_proc.cc with an older version (Doxygen 1.3.8 on
>>Windows) and observed the same the behaviour.
>> 
>>I looks like the commands used in the test case are missing the a
>>description block.
>> 
>>Is this intended?
>> 
>>When using /interface and /class commands, you need to following with a
>>description block. Among others, you use these commands if you need to
>>locate the description the software entity in a different location (i.e. not
>>collocated in a separate file or different location within the same file).
>> 
>>If you try this test case (added description block):/// \interface Int
>>/// This is an interface class
>>class Int
>>{
>>    virtual ~Int() {}
>>    virtual void Method() = 0;
>>};
>>/// \class Imp
>>/// This is the implementation of the class interface.
>>class Imp : public Int
>>{
>>    void Method() {}
>>};
>>
>>Then no warnings.
>>
>>Now, is it the expected behaviour. Should doxygen not generate a warning if
>>the description block is missing?
>>    
>>
>
>I think (haven't checked) it is more the difference between a brief
>and a detailed description. Probably the \class command is allowed in
>a brief description and the \interface command is not. I'm working on
>a new scanner for comment blocks which should bring some more
>consistency to handling of brief and detailed descriptions w.r.t. the
>handling of commands.
>
>Regards,
>  Dimitri
>
>
>-------------------------------------------------------
>This SF.Net email is sponsored by: IntelliVIEW -- Interactive Reporting
>Tool for open source databases. Create drag-&-drop reports. Save time
>by over 75%! Publish reports on the web. Export to DOC, XLS, RTF, etc.
>Download a FREE copy at http://www.intelliview.com/go/osdn_nl
>_______________________________________________
>Doxygen-develop mailing list
>Dox...@li...
>https://lists.sourceforge.net/lists/listinfo/doxygen-develop
>
>  
>

Re: [Doxygen-develop] \interface tag - possible bug?

[Dimitri v. H. <do...@gm...>]

On Fri, 21 Jan 2005 08:50:47 -0400, Christian Baribeau
<chr...@am...> wrote:
> Allo James!
>  
> Just to further amplified your email message.
>  
> I ran the test case test_proc.cc with an older version (Doxygen 1.3.8 on
> Windows) and observed the same the behaviour.
>  
> I looks like the commands used in the test case are missing the a
> description block.
>  
> Is this intended?
>  
> When using /interface and /class commands, you need to following with a
> description block. Among others, you use these commands if you need to
> locate the description the software entity in a different location (i.e. not
> collocated in a separate file or different location within the same file).
>  
> If you try this test case (added description block):/// \interface Int
> /// This is an interface class
> class Int
> {
>     virtual ~Int() {}
>     virtual void Method() = 0;
> };
> /// \class Imp
> /// This is the implementation of the class interface.
> class Imp : public Int
> {
>     void Method() {}
> };
> 
> Then no warnings.
> 
> Now, is it the expected behaviour. Should doxygen not generate a warning if
> the description block is missing?

I think (haven't checked) it is more the difference between a brief
and a detailed description. Probably the \class command is allowed in
a brief description and the \interface command is not. I'm working on
a new scanner for comment blocks which should bring some more
consistency to handling of brief and detailed descriptions w.r.t. the
handling of commands.

Regards,
  Dimitri

Re: [Doxygen-develop] \interface tag - possible bug?

[Christian B. <chr...@am...>]

Allo James!

Just to further amplified your email message.

I ran the test case test_proc.cc with an older version (Doxygen 1.3.8 on =
Windows) and observed the same the behaviour.

I looks like the commands used in the test case are missing the a =
description block.

Is this intended?

When using /interface and /class commands, you need to following with a =
description block. Among others, you use these commands if you need to =
locate the description the software entity in a different location (i.e. =
not collocated in a separate file or different location within the same =
file).

If you try this test case (added description block):
/// \interface Int/// This is an interface classclass Int{    virtual =
~Int() {}    virtual void Method() =3D 0;};/// \class Imp/// This is the =
implementation of the class interface.class Imp : public Int{    void =
Method() {}};Then no warnings.

Now, is it the expected behaviour. Should doxygen not generate a warning =
if the description block is missing?

Regards,

Christian

  ----- Original Message -----=20
  From: James Hobro=20
  To: dox...@li...=20
  Sent: Thursday, January 20, 2005 4:36 PM
  Subject: [Doxygen-develop] \interface tag - possible bug?


  Hi,

  The \interface tag, which is documented in the Doxygen manual, appears =
not to be=20
  recognised by Doxygen 1.4.1:

  test_prog.cc:

  /// \interface Int
  class Int
  {
      virtual ~Int() {}
      virtual void Method() =3D 0;
  };

  /// \class Imp
  class Imp : public Int
  {
      void Method() {}
  };


  Running Doxygen 1.4.1 (on Linux) on test_prog.cc produces the warning

  test_prog.cc:1: Warning: Found unknown command `\interface'

  and Int and Imp are both documented as regular classes.

  Is this a bug?

  Regards,

  James.



  -------------------------------------------------------
  This SF.Net email is sponsored by: IntelliVIEW -- Interactive =
Reporting
  Tool for open source databases. Create drag-&-drop reports. Save time
  by over 75%! Publish reports on the web. Export to DOC, XLS, RTF, etc.
  Download a FREE copy at http://www.intelliview.com/go/osdn_nl
  _______________________________________________
  Doxygen-develop mailing list
  Dox...@li...
  https://lists.sourceforge.net/lists/listinfo/doxygen-develop

[Doxygen-develop] \interface tag - possible bug?

[James H. <jh...@ga...>]

Hi,

The \interface tag, which is documented in the Doxygen manual, appears not to be 
recognised by Doxygen 1.4.1:

test_prog.cc:

/// \interface Int
class Int
{
    virtual ~Int() {}
    virtual void Method() = 0;
};

/// \class Imp
class Imp : public Int
{
    void Method() {}
};


Running Doxygen 1.4.1 (on Linux) on test_prog.cc produces the warning

test_prog.cc:1: Warning: Found unknown command `\interface'

and Int and Imp are both documented as regular classes.

Is this a bug?

Regards,

James.

[Doxygen-develop] Doxygen version 1.4.1 available for testing

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

Hi,

I've made a new version of doxygen available from 
ftp://ftp.stack.nl/pub/doxygen (look for version label 1.4.1). 
This is not an "official" release yet, but I would like to invite those who 
have experienced crashes with version 1.4.0 to try this version and let me 
know whether or not the problems are fixed.

Thanks for your help,
  Dimitri

Re: [Doxygen-develop] Bug in 1.4.0?

[Cadle, B. <bc...@ar...>]

First,
	Thank you Dimitri for creating Doxygen and putting in the effort to =
maintain the application.  Doxygen is a much better application than =
most of the other alternatives I found on the world wide web.

Second,
	Given your response below I have an additional request or item for the =
wish list.  My request is at the bottom of the thread.


On Wed, 5 Jan 2005 at 11:46:10 +0100, Dimitri van Heesch wrote:
>On Mon, Jan 03, 2005 at 11:20:51PM -0600, Dan Gass wrote:
> > On Mon, 3 Jan 2005 14:19:25 -0800, Cadle, Brad <bc...@ar...> =
wrote:
> > > I noticed that in moving from version 1.3.9.1 to 1.4.0 the =
behavior of the \todo command seems have been broken:
> > >=20
> > > in 1.3.9.1 all the /todo commands for a single C function are =
grouped under a single heading in the file reference.
> > >=20
> > > In 1.4.0 Each /todo command in the file reference for a single =
function results in a separate heading in the file reference.
> > >=20
> > > Example:
> > >=20
> > >    /** \todo Fill out function. */
> > >=20
> > >    /** \req Complies with requirement squiggy */
> > >=20
> > >    /** \ps Test Psuedo Code line 1 \endps */
> > >=20
> > >    /** \todo Remove ret =3D 1. *
> > >=20
> > > (NOTE: /ps is an alias I defined)
> > >=20
> > > 1.3.9.1, I get for the file reference
> > >=20
> > > Todo:
> > >     Fill out function.
> > >=20
> > >     Remove ret =3D 1.
> > >=20
> > > Requirements:
> > >     Complies with requirement squiggy
> > >=20
> > > Pseudo Code:
> > >     Test Psuedo Code line 1
> > >=20
> > > 1.4.0, I get for the file reference
> > >
> > > Todo:
> > >     Fill out function.
> > >=20
> > > Requirements:
> > >     Complies with requirement squiggy
> > >=20
> > > Pseudo Code:
> > >     Test Psuedo Code line 1
> > >=20
> > > Todo:
> > >     Remove ret =3D 1.
> > >=20
> > > Clearly, 1.3.9.1 is desirable.
> > >
> >=20
> > This may be a result of a bug fix (id 157485) I'll let Dimitri =
comment
> > further.
> >=20
>
> As Dan mentioned, this was the result of some people (Dan was one of =
them)
> reporting that the order in which they placed their commands was not=20
> maintained. I think there is something to say for that as well
> (especially since the same is not done for other commands such as =
@warning).
> So I think it not so clear that the pre-1.4.0 behaviour was better.
>=20
> Regards,
>  Dimitri


Given that it is not clear that the pre-1.4.0 behavior is better, Can =
you add
an option to the Doxygen config file that lets this behavior be toggled =
on and off. =20
For Example, you could define GROUP_TODO_ITEMS and have YES be pre-1.4.0 =
behavior
and NO be 1.4.0.  If you do take this route, I recommend you do that for =
all similar
items in Doxygen.  Since xrefitems also appear in the function =
documentation (optionally)
it would also be useful to have GROUP_XREF_ITEMS. =20

Regards,
Brad



--__--__--

Message: 2
Date: Wed, 5 Jan 2005 11:58:11 +0100
From: Dimitri van Heesch <di...@st...>
To: Richard Pillay <RPD...@Ya...>
Cc: DOxygen Developer's List <dox...@li...>
Subject: Re: [Doxygen-develop] Bug in 1.4.0

On Wed, Jan 05, 2005 at 11:37:15AM +1100, Richard Pillay wrote:
> Hi Guys,
>=20
> I've just changed from 1.3.9.1 to 1.4.0 and Doxygen crashed on me =
under Windows. I eventually narrowed it down to the following type of =
line in a text file:
>=20
>=20
> One,2,three,four
>=20
>=20
> If you place the line in a text file and include it in what doxygen is =
documenting, it crashes. This did not happen previously.
>=20
> Dimitri, if you don't have time to look at it, could you give me a =
idea where to look and I'll download the source and see what I can find.

I take crash reports very seriously. They get the highest priority, so I
have time to look at your problem, but first I need to be able to =
reproduce it.

Your description is not clear enough for me to actually reproduce the =
crash.
Please tell me:
- The exact config file (or difference w.r.t. the default)
- The source code you used (file name(s) + content)
- The platform you use (variant of windows in your case).
- The version of doxygen (1.4.0 in your case, but was it the binary =
version
or did you compile it yourself?)

If possible bundle the files in a zip, verify that the problem is still=20
reproducable and send the zip to me (or to the list if the zip is very =
small).=20
The bug tracker is an even better way to report bugs.=20

Regards,
  Dimitri


--__--__--

Message: 3
Date: Wed, 5 Jan 2005 13:06:02 +0100
From: Dimitri van Heesch <do...@gm...>
Reply-To: di...@st...
To: "Cadle, Brad" <bc...@ar...>
Cc: dox...@li..., =
dox...@li....
Subject: [Doxygen-develop] Re: [Doxygen-users] Wish list (or is it =
present?): Order of routines in Call Graph.

On Mon, 3 Jan 2005 13:56:05 -0800, Cadle, Brad <bc...@ar...> wrote:
> I apologize if this has been addressed elsewhere, but my question is =
this:
>=20
> I have not found a way to specify that the order of appearance of the =
routines in the Call Graphs reflect the order in which they are in the =
code.
>=20
> For Example I would like:
>=20
> int main(int argc, char *argv[])
> {
>         int ack;
>=20
>         ack =3D Foo();
>         if (ack)
>         {
>            Bar();
>         }
>         Yin();
>         Yang();
>=20
>         return ack;
> }
>=20
> to produce something like this:
>=20
> main
> |
> |
> |
> ---------------------
> |       |       |       |
> Foo  Bar   Yin  Yang
>=20
> and not some other order of appearance of Foo Bar Yin Yang.
>=20
> Will this eventually be possible or is there already a mechanism to do =
this?

Doxygen uses dot to layout the graph. Dot doesn't know about the
calling order so it
will not keep it. I don't know how one could prescribe such order using =
dot.

Regards,
  Dimitri



--__--__--

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


End of Doxygen-develop Digest

[Doxygen-develop] Re: [Doxygen-users] Wish list (or is it present?): Order of routines in Call Graph.

[Dimitri v. H. <do...@gm...>]

On Mon, 3 Jan 2005 13:56:05 -0800, Cadle, Brad <bc...@ar...> wrote:
> I apologize if this has been addressed elsewhere, but my question is this:
> 
> I have not found a way to specify that the order of appearance of the routines in the Call Graphs reflect the order in which they are in the code.
> 
> For Example I would like:
> 
> int main(int argc, char *argv[])
> {
>         int ack;
> 
>         ack = Foo();
>         if (ack)
>         {
>            Bar();
>         }
>         Yin();
>         Yang();
> 
>         return ack;
> }
> 
> to produce something like this:
> 
> main
> |
> |
> |
> ---------------------
> |       |       |       |
> Foo  Bar   Yin  Yang
> 
> and not some other order of appearance of Foo Bar Yin Yang.
> 
> Will this eventually be possible or is there already a mechanism to do this?

Doxygen uses dot to layout the graph. Dot doesn't know about the
calling order so it
will not keep it. I don't know how one could prescribe such order using dot.

Regards,
  Dimitri

Re: [Doxygen-develop] Bug in 1.4.0

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

On Wed, Jan 05, 2005 at 11:37:15AM +1100, Richard Pillay wrote:
> Hi Guys,
> 
> I've just changed from 1.3.9.1 to 1.4.0 and Doxygen crashed on me under Windows. I eventually narrowed it down to the following type of line in a text file:
> 
> 
> One,2,three,four
> 
> 
> If you place the line in a text file and include it in what doxygen is documenting, it crashes. This did not happen previously.
> 
> Dimitri, if you don't have time to look at it, could you give me a idea where to look and I'll download the source and see what I can find.

I take crash reports very seriously. They get the highest priority, so I
have time to look at your problem, but first I need to be able to reproduce it.

Your description is not clear enough for me to actually reproduce the crash.
Please tell me:
- The exact config file (or difference w.r.t. the default)
- The source code you used (file name(s) + content)
- The platform you use (variant of windows in your case).
- The version of doxygen (1.4.0 in your case, but was it the binary version
or did you compile it yourself?)

If possible bundle the files in a zip, verify that the problem is still 
reproducable and send the zip to me (or to the list if the zip is very small). 
The bug tracker is an even better way to report bugs. 

Regards,
  Dimitri

Re: [Doxygen-develop] Bug in 1.4.0?

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

On Mon, Jan 03, 2005 at 11:20:51PM -0600, Dan Gass wrote:
> On Mon, 3 Jan 2005 14:19:25 -0800, Cadle, Brad <bc...@ar...> wrote:
> > I noticed that in moving from version 1.3.9.1 to 1.4.0 the behavior of the \todo command seems have been broken:
> > 
> > in 1.3.9.1 all the /todo commands for a single C function are grouped under a single heading in the file reference.
> > 
> > In 1.4.0 Each /todo command in the file reference for a single function results in a separate heading in the file reference.
> > 
> > Example:
> > 
> >    /** \todo Fill out function. */
> > 
> >    /** \req Complies with requirement squiggy */
> > 
> >    /** \ps Test Psuedo Code line 1 \endps */
> > 
> >    /** \todo Remove ret = 1. *
> > 
> > (NOTE: /ps is an alias I defined)
> > 
> > 1.3.9.1, I get for the file reference
> > 
> > Todo:
> >     Fill out function.
> > 
> >     Remove ret = 1.
> > 
> > Requirements:
> >     Complies with requirement squiggy
> > 
> > Pseudo Code:
> >     Test Psuedo Code line 1
> > 
> > 1.4.0, I get for the file reference
> > 
> > Todo:
> >     Fill out function.
> > 
> > Requirements:
> >     Complies with requirement squiggy
> > 
> > Pseudo Code:
> >     Test Psuedo Code line 1
> > 
> > Todo:
> >     Remove ret = 1.
> > 
> > Clearly, 1.3.9.1 is desirable.
> > 
> 
> This may be a result of a bug fix (id 157485) I'll let Dimitri comment
> further.
> 

As Dan mentioned, this was the result of some people (Dan was one of them)
reporting that the order in which they placed their commands was not 
maintained. I think there is something to say for that as well
(especially since the same is not done for other commands such as @warning).
So I think it not so clear that the pre-1.4.0 behaviour was better.

Regards,
  Dimitri

[Doxygen-develop] Bug in 1.4.0

[Richard P. <RPD...@Ya...>]

Hi Guys,

I've just changed from 1.3.9.1 to 1.4.0 and Doxygen crashed on me under Windows. I eventually narrowed it down to the following type of line in a text file:


One,2,three,four


If you place the line in a text file and include it in what doxygen is documenting, it crashes. This did not happen previously.

Dimitri, if you don't have time to look at it, could you give me a idea where to look and I'll download the source and see what I can find.

Best Regards,
Richard.

Re: [Doxygen-develop] Bug in 1.4.0?

[Dan G. <dan...@gm...>]

On Mon, 3 Jan 2005 14:19:25 -0800, Cadle, Brad <bc...@ar...> wrote:
> I noticed that in moving from version 1.3.9.1 to 1.4.0 the behavior of the \todo command seems have been broken:
> 
> in 1.3.9.1 all the /todo commands for a single C function are grouped under a single heading in the file reference.
> 
> In 1.4.0 Each /todo command in the file reference for a single function results in a separate heading in the file reference.
> 
> Example:
> 
>    /** \todo Fill out function. */
> 
>    /** \req Complies with requirement squiggy */
> 
>    /** \ps Test Psuedo Code line 1 \endps */
> 
>    /** \todo Remove ret = 1. *
> 
> (NOTE: /ps is an alias I defined)
> 
> 1.3.9.1, I get for the file reference
> 
> Todo:
>     Fill out function.
> 
>     Remove ret = 1.
> 
> Requirements:
>     Complies with requirement squiggy
> 
> Pseudo Code:
>     Test Psuedo Code line 1
> 
> 1.4.0, I get for the file reference
> 
> Todo:
>     Fill out function.
> 
> Requirements:
>     Complies with requirement squiggy
> 
> Pseudo Code:
>     Test Psuedo Code line 1
> 
> Todo:
>     Remove ret = 1.
> 
> Clearly, 1.3.9.1 is desirable.
> 

This may be a result of a bug fix (id 157485) I'll let Dimitri comment
further.

I've also noticed peculiar behavior with alias/xrefitem entries in
function bodies (I don't believe it is new though).  For example in my
Doxygen configuration file I define an alias "future" to be a
xrefitem.  I use @future inside of function bodies following a ///
comment delimiter.  Sometimes Doxygen will complain about an unknown
\future command (with a slightly inaccurate source line number) and
the text following the @future gets merged with the previous
paragraph.  I can work around the problem by putting a blank /// ahead
of it.  I will eventually characterize this better and submit a bug
but I thought I would mention it if you were in the area :-).

Kudos (and many thanks) Dimitri for your quality software.  I have
been active in some Python related open source activities and am
getting an appreciation for how much work and dedication goes into
projects like this.

Best Regards,
Dan Gass

[Doxygen-develop] Bug in 1.4.0?

[Cadle, B. <bc...@ar...>]

I noticed that in moving from version 1.3.9.1 to 1.4.0 the behavior of =
the \todo command seems have been broken:

in 1.3.9.1 all the /todo commands for a single C function are grouped =
under a single heading in the file reference. =20

In 1.4.0 Each /todo command in the file reference for a single function =
results in a separate heading in the file reference.



Example:

   /** \todo Fill out function. */
  =20
   /** \req Complies with requirement squiggy */=20

   /** \ps Test Psuedo Code line 1 \endps */

   /** \todo Remove ret =3D 1. *



(NOTE: /ps is an alias I defined)


1.3.9.1, I get for the file reference
    =09
Todo:
    Fill out function.

    Remove ret =3D 1.

Requirements:
    Complies with requirement squiggy

Pseudo Code:
    Test Psuedo Code line 1=20



1.4.0, I get for the file reference

Todo:
    Fill out function.

Requirements:
    Complies with requirement squiggy

Pseudo Code:
    Test Psuedo Code line 1=20

Todo:
    Remove ret =3D 1.



Clearly, 1.3.9.1 is desirable.=20

[Doxygen-develop] Wish list (or is it present?): Order of routines in Call Graph.

[Cadle, B. <bc...@ar...>]

I apologize if this has been addressed elsewhere, but my question is =
this:

I have not found a way to specify that the order of appearance of the =
routines in the Call Graphs reflect the order in which they are in the =
code.

For Example I would like:

int main(int argc, char *argv[])
{
	int ack;

	ack =3D Foo();
	if (ack)
	{
	   Bar();
	}
	Yin();
	Yang();

	return ack;
}

to produce something like this:

main
|
|
|
---------------------
|	|	|	|
Foo  Bar   Yin	Yang


and not some other order of appearance of Foo Bar Yin Yang.


Will this eventually be possible or is there already a mechanism to do =
this?

Re: [Doxygen-develop] Re: Support for other languages

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

On Sun, Dec 26, 2004 at 10:52:24AM -0800, Vicki Brown wrote:
> At 10:56 +0100 12/25/2004, Dimitri van Heesch <di...@st...> wrote:
> >You can already show the original python sources by setting
> >FILTER_SOURCE_FILES to NO. The main problem is that doxygen does not
> >understand python so it will not do syntax highlighting and cross-referencing
> >properly.
> 
> Yes, I _know_ that. That's rather the point.
> 
> I want both the cross referencing as well as the Python source.
> 
> So I ask again:
> 
>  If the filters passed along both the translated code and the original
>  code, Doxygen could use the former for its analysis and the latter for
>  its code displays.  Ideally, this would involve an extension of the
>  current interface, so that existing filters would still work as they
>  do now.
> 
>  How difficult would this be?

Difficult. Imagine that in the filtered code a function call is found
at line x, column y. Then for the unfiltered Python code I would need to
know the corresponding location (x',y'), at which the function is definition 
in the Python source is present in order to make a link (and cross-reference 
with the documentation). How can doxygen compute this if it does not 
understand the unfiltered code? A function call is one example, but the 
same holds for function body start and end, location of a class definition, 
etc, etc. 

So this would only work if either the filter is very simple
(think of simple word replacements), or if both scanner.l and code.l are
rewritten/extended so they understand Python.

Regards,
  Dimitri

[Doxygen-develop] Re: Support for other languages

[Vicki B. <vl...@cf...>]

At 10:56 +0100 12/25/2004, Dimitri van Heesch <di...@st...> wrote:
>You can already show the original python sources by setting
>FILTER_SOURCE_FILES to NO. The main problem is that doxygen does not
>understand python so it will not do syntax highlighting and cross-referencing
>properly.

Yes, I _know_ that. That's rather the point.

I want both the cross referencing as well as the Python source.

So I ask again:

 If the filters passed along both the translated code and the original
 code, Doxygen could use the former for its analysis and the latter for
 its code displays.  Ideally, this would involve an extension of the
 current interface, so that existing filters would still work as they
 do now.

 How difficult would this be?

> P.S. For Python you could also look at: pydoc, happydoc, or epydoc.

I have looked at them. Doxygen is miles better. Except for the fact that it
makes everything look like C++. Happydoc is... oddly formatted. epydoc
refuses to traverse directory trees. Neither of these seems to understand
source code or cross references very well. I haven't looked at pydoc (my
understanding is that epydoc was written to address lack of functionality in
pydoc and epydoc is lacking in functionality itself).
-- 
Vicki Brown     ZZZ                Journeyman Sourceror:
SF Bay Area, CA    zz  |\     _,,,---,,_      Scripts & Philtres
http://www.cfcl.com zz /,`.-'`'    -.  ;-;;,_Code, Doc, Process, QA
http://cfcl.com/vlb   |,4-  ) )-,_. ,\ ( `'-'Perl, Unix, Mac OS X, WWW
____________________ '---''(_/--'  `-'\_)  ___________________________

Re: [Doxygen-develop] Support for other languages

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

On Thu, Dec 23, 2004 at 01:49:37PM -0800, Vicki Brown wrote:
> I've been examining and comparing several "code documentation tools".
> Having looked at several now, I really like Doxygen. In fact, I would
> love to use Doxygen except for one show-stopper difficulty. The Company
> where I am currently employed (where I would most likely deploy Doxygen)
> uses Python.
> 
> But... Doxygen allows the use of input filters which convert snippets
> of code (e.g., data structure declarations, method calls) from non-C++
> languages into C++ syntax.  Doxygen is then able to create web pages,
> diagrams, etc. This looked promising.
> 
> I found pydoxy and was quite pleased ... at first. Then I discovered
> that the code listings in the resulting HTML pages _still look like
> C++_.  This is not so promising.
> 
> While I can certainly understand why the filter creates "pseudo" C++
> code out of the Python code, that isn't what the  ultimate web pages
> should show to developers who want to browse that code. The developers
> wrote Python; they want to browse Python.
> 
> The Doxygen Wish List lists "support for other languages" as a 10 in
> difficulty. I would dearly love to see this item fulfilled.
> 
> However, I do not think that all languages should be equally difficult to
> support. Languages that already have a filter (e.g. Python) _could_ be much
> easier to support if the filter mechanism can be leveraged.
> 
> If the filters passed along both the translated code and the original
> code, Doxygen could use the former for its analysis and the latter for
> its code displays.  Ideally, this would involve an extension of the
> current interface, so that existing filters would still work as they
> do now.
> 
> How difficult would this be?

You can already show the original python sources by setting 
FILTER_SOURCE_FILES to NO. The main problem is that doxygen does not
understand python so it will not do syntax highlighting and cross-referencing
properly. 

To understand this better you should know that doxygen has two independent 
"parsers" for source code:

- scanner.l: which analyses the structure of code and parses any 
  supported language to generate plain documentation. It basically parses
  only the outline of the source code (not the body of functions). 
- code.l: which filters the source code and uses the information found
  by scanner.l to keep track where functions/classes start and end.
  In this step the cross-references are computed. The filter is single pass,
  so the correct result is directly written to the output without creating
  an intermediate representation first (like a real compiler would do).

So if you transform a piece of code with a filter (and not just substitutes
some words) you should also use the same filter to get syntax-highlighting 
and cross-referencing correct (i.e. FILTER_SOURCE_FILES = YES). Since 
there is no intermediate representation for function bodies, it is very 
hard to keep a mapping of where things in the filtered source file are 
located in the original source, which is what you are asking for.

Conclusion is that it is hard to *properly* support additional languages.
In general the more a language resembles one of the supported languages the 
easier it is to add support for it. So adding support for say JavaScript is 
easier than adding support for Python, which is again easier than adding
support for VHDL.

I've been thinking about making parsers more "pluggable" but for now this
is still long term stuff.

Regards,
  Dimitri

P.S. For Python you could also look at: pydoc, happydoc, or epydoc.

[Doxygen-develop] Support for other languages

[Vicki B. <vl...@cf...>]

I've been examining and comparing several "code documentation tools".
Having looked at several now, I really like Doxygen. In fact, I would
love to use Doxygen except for one show-stopper difficulty. The Company
where I am currently employed (where I would most likely deploy Doxygen)
uses Python.

But... Doxygen allows the use of input filters which convert snippets
of code (e.g., data structure declarations, method calls) from non-C++
languages into C++ syntax.  Doxygen is then able to create web pages,
diagrams, etc. This looked promising.

I found pydoxy and was quite pleased ... at first. Then I discovered
that the code listings in the resulting HTML pages _still look like
C++_.  This is not so promising.

While I can certainly understand why the filter creates "pseudo" C++
code out of the Python code, that isn't what the  ultimate web pages
should show to developers who want to browse that code. The developers
wrote Python; they want to browse Python.

The Doxygen Wish List lists "support for other languages" as a 10 in
difficulty. I would dearly love to see this item fulfilled.

However, I do not think that all languages should be equally difficult to
support. Languages that already have a filter (e.g. Python) _could_ be much
easier to support if the filter mechanism can be leveraged.

If the filters passed along both the translated code and the original
code, Doxygen could use the former for its analysis and the latter for
its code displays.  Ideally, this would involve an extension of the
current interface, so that existing filters would still work as they
do now.

How difficult would this be?
-- 
Vicki Brown     ZZZ                Journeyman Sourceror:
SF Bay Area, CA    zz  |\     _,,,---,,_      Scripts & Philtres
http://www.cfcl.com zz /,`.-'`'    -.  ;-;;,_Code, Doc, Process, QA
http://cfcl.com/vlb   |,4-  ) )-,_. ,\ ( `'-'Perl, Unix, Mac OS X, WWW
____________________ '---''(_/--'  `-'\_)  ___________________________

[Doxygen-develop] [Patch] New parameter DOT_TRANSPARENT

[Maik H. <ma...@hi...>]

Hello,

I need transparent graphics for some of our documentation and imho it is 
not so manageable to toggle define DOT_TRANSPARENT in file dot.cpp.

So please find attached patch that defines a config parameter 
DOT_TRANSPARENT to use it in dot.cpp and dirdef.cpp.

Please note that patch of file config.l contains new parameter 
FILE_VERSION_INFO too, which is part of my "file version numbers.

Cu,
Maik