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

[Doxygen-develop] [PATCH] New output format

[Miguel <mig...@te...>]

Hi.

This is a patch against current CVS to add a new output format I've 
called "Perl".  "Perl" is intended as an intermediate format that can 
be used to generate new and customized output formats without having 
to modify the Doxygen source.  I think it can coexist with the XML 
intermediate format that it is currently being worked on; "Perl" is 
simpler and easier to use but not as standard and powerful as XML.

The name "Perl" is because, you guessed it, the output consists of 
Perl code.  When you activate the new GENERATE_PERL config option, a 
Perl module called "DoxyDocs.pm" is created in the user's 
OUTPUT_DIRECTORY.  Then the user can run a custom Perl script using 
that Perl module to generate the desired output format.

The contents of the Perl module is a single statement, assigning to 
the variable $doxydocs a reference to a tree-like structure composed 
of anonymous hashes and arrays.  I think this method is at the same 
time flexible and easy to use.

Also attached is an example Perl script that generates a simple 
human-readable text format using DoxyDocs.pm.

Please note that the Perl output format is at the moment fairly 
incomplete and probably buggy.  I'm sending it so I can get your 
comments and suggestions.  If the feedback is positive I will try to 
complete it before the next Doxygen release.

So, what do you think about it?

--
Miguel

[Doxygen-develop] RE: [Doxygen-users] How to hide compounds

[Richard G. <rg...@ta...>]

On Tue, 3 Sep 2002, Glenn Maxey wrote:

> For those who want to hide things without preprocessing, read this with
> an open mind anyway even though preprocessing is what it advocates.

Well - I think for someone who is familiar with the parser structure of
doxygen it would be very easy to add a new special command to mark the
following entity as "hidden" and just do not insert it to any symbol table
doxygen maintains. Ok, I know nothing about the inners of doxygen, but
with any reasonable parser structure this should be very well possible.
May I suggest @hidden?

Any takers?

   Thanks, Richard.

> > -----Original Message-----
> > From: Richard Guenther [mailto:rg...@ta...]
> > Sent: Tuesday, September 03, 2002 8:02 AM
> > To: dox...@li...
> > Subject: [Doxygen-users] How to hide compounds
>
> <snip>
>
> > Is there a way to make doxygen ignore a compound besides of using
> > preprocessor tricks (which pollute the code too much and make it less
> > readable, I think)?
>

--
Richard Guenther <ric...@un...>
WWW: http://www.tat.physik.uni-tuebingen.de/~rguenth/
The GLAME Project: http://www.glame.de/

[Doxygen-develop] Building Doxygen 1.2.17 in Windows

[Simon G. <sim...@at...>]

Dimitri wrote:

> Bison problems 
> This problem has been solved in version 1.35 
> (versions before 1.31 will also work). 
> 
> i.e. time to upgrade bison.

OK, the latest Cygwin includes 1.35 and did indeed
fix the problem - I commend that to others running
Doxygen on Win32.

> > I needed to add the following to the project file to get 
> > it to build from the VC++6 IDE:
> > 
> > src\docparser.cpp
> > src\docparser.h
> > src\doctokeniser.h
> > src\doctokeniser.cpp
> > src\cmdmapper.cpp
> > src\cmdmapper.h
> 
> For completeness could you please also include:
>   src\docvisitor.h
>   src\printdocvisitor.h

OK, I have done so (attached). The following caveat still applies:
 
> > I attach an updated DSP file which encapsulates these additions. Note
> > that you still need to run 'make msvc' once from the command line
> > before the IDE build will work. That's because VC++6 does not know
> > how to parse the flex and bison files that generate some of the C source...
> > Once you've run that make once, you can build variants from the IDE... 

Cheers

Simon Goodwin
Technology Programmer, ATD

-- 
Simon Goodwin <sim...@at...>

[Doxygen-develop] [PATCH] New configuration option to hide friend compounds

[Morten E. <mo...@si...>]

Hi,

this patch makes it possible to avoid having C++ "friend class ...",
"friend union ..." and "friend struct ..." items show up in the class
summary at the top of the output.

I think this is most often the wanted behavior for large class
libraries, as I believe "friend class" statements are usually only of
interest for knowing details of the internal implementation of the
library -- and is of no interest or consequence to the application
programmer.

The patch implements a new configuration variable
"HIDE_FRIEND_COMPOUNDS" to make it possible to exclude friend
compounds from the documentation:

---8<---- [snip] --------8<---- [snip] --------8<---- [snip] -----

--- memberdef.cpp	Tue Aug 13 12:19:14 2002
+++ ../../doxygen-1.2.17/src/memberdef.cpp	Tue Aug 13 12:13:42 2002
@@ -580,6 +580,14 @@
                              Config_getBool("EXTRACT_PRIVATE") ||
                              mtype==Friend
                             );
+
+    // Hide friend (class|struct|union) declarations if HIDE_FRIEND_COMPOUNDS is true
+    bool visibleIfFriendCompound = !(Config_getBool("HIDE_FRIEND_COMPOUNDS") &&
+                                    isFriend() &&
+                                    (type=="friend class" || type=="friend struct" || 
+                                     type=="friend union"
+                                    )
+                                   );
     
     // hide member if it overrides a member in a superclass and has no
     // documentation
@@ -607,7 +615,8 @@
 
     bool visible = visibleIfStatic && visibleIfDocumented && 
                    visibleIfEnabled && visibleIfPrivate &&
-                   visibleIfDocVirtual && visibleIfNotDefaultCDTor && !annScope;
+                   visibleIfDocVirtual && visibleIfFriendCompound &&
+                   visibleIfNotDefaultCDTor && !annScope;
     //printf("MemberDef::isBriefSectionVisible() %d\n",visible);
     return visible;
 }
--- config.cpp	Mon Jul 15 13:34:52 2002
+++ ../../doxygen-1.2.17/src/config.cpp	Tue Aug 13 12:20:53 2002
@@ -3116,6 +3116,14 @@
                     FALSE
                  );
   cb = addBool(
+                    "HIDE_FRIEND_COMPOUNDS",
+                    "If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all \n"
+                    "friend (class|struct|union) declarations. \n"
+                    "If set to NO (the default) these declarations will be included in the \n"
+                    "documentation. \n",
+                    FALSE
+                 );
+  cb = addBool(
                     "BRIEF_MEMBER_DESC",
                     "If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will \n"
                     "include brief member descriptions after the members that are listed in \n"


---8<---- [snip] --------8<---- [snip] --------8<---- [snip] -----

(Credit for the patch yet again goes to my colleague Kristian Eide.)

Best regards,
Morten

[Doxygen-develop] [PATCH] Kill warnings on un-documented private compunds

[Morten E. <mo...@si...>]

Hi,

I have another patch, this time for the following problem, reported a
couple of weeks ago:

> I have an annoying problem with Doxygen (tested with released
> version 1.2.17). This declaration in a .h file:
> 
> ----8<---- [snip] ---------8<---- [snip] ---------8<---- [snip] -----
> 
> class MyClass {
> private:
>   struct ShouldNotBeDocumented {
>   };
> };
> 
> ----8<---- [snip] ---------8<---- [snip] ---------8<---- [snip] -----
> 
> ..will cause doxygen to emit the following warning:
> 
> <...>/private_struct.h:3: Warning: Compound MyClass::ShouldNotBeDocumented is not documented.
> 
> [...]
> 
> This seems like a bug to me, as the default value of EXTRACT_PRIVATE
> is "NO"?

Here is the patch (yet again done by my colleague Kristian Eide):

----8<---- [snip] -------8<---- [snip] -------8<---- [snip] ---
--- doxygen.cpp	Sun Jul 14 18:27:42 2002
+++ ../../doxygen-1.2.17/src/doxygen.cpp	Tue Aug 13 11:39:46 2002
@@ -3255,7 +3255,8 @@
         bName.right(2)!="::")
     {
       if (!root->name.isEmpty() && root->name[0]!='@' &&
-          (guessSection(root->fileName)==Entry::HEADER_SEC || Config_getBool("EXTRACT_LOCAL_CLASSES"))
+          (guessSection(root->fileName)==Entry::HEADER_SEC || Config_getBool("EXTRACT_LOCAL_CLASSES") &&
+          (root->protection!=Private || Config_getBool("EXTRACT_PRIVATE")))
          )
         warn_undoc(
                    root->fileName,root->startLine,
----8<---- [snip] -------8<---- [snip] -------8<---- [snip] ---

Best regards, 
Morten

[Doxygen-develop] [PATCH] Re: [Doxygen-users] Avoiding repeated documentation on inherited members?

[Morten E. <mo...@si...>]

Morten Eriksen <mo...@si...> writes:

> I wondering if it's possible to configure Doxygen to _not_ repeat
> the documentation on C++ inherited members of subclasses?

Replying to my own post here... anyway, I had a problem described like
this:

> IMHO, this feature tends to clutter up the API documentation more
> than it clarifies -- at least for the particular class library I'm
> documenting.
> 
> An example to make myself clear:
> 
> ----8<--- [snip] ---------8<--- [snip] ---------8<--- [snip] -----
> 
> //! This class blablabla...
> class Super {
> public:
>         //! This method blablabla...
>         virtual void aVirtualMethod(void);
> };
> 
> //! This class blablabla...
> class Sub : class Super {
> public:
>         virtual void aVirtualMethod(void);
> };
> 
> ----8<--- [snip] ---------8<--- [snip] ---------8<--- [snip] -----
> 
> Now, for class Sub, aVirtualMethod() will be included in the
> documentation, just repeating the documentation of this method in
> the Super class. I would like to avoid that, to "clean up" and
> remove unnecessary clutter in a huge, fine-grained class library I
> have documented here.

..and another problem described like this:

> [...] is it possible to configure Doxygen to not output
> non-documented default constructors and destructors of a C++ class?
> 
> The documentation for default constructors usually just ends up as
> 
>         //! Default constructor.
>         MyClass::MyClass(void) { [...] }
> 
> or
> 
>         //! Default constructor, initializes internal member variables.
>         MyClass::MyClass(void) { [...] }
> 
> and for the destructor
> 
>         //! Destructor, deallocates resources used by class instance.
>         MyClass::~MyClass() { [...] }
> 
> ..or something in this vein -- which of course is completely worthless
> to the application programmer, so it could just as well have been left
> out. *Not* documenting the default constructors and/or the destructor
> could be sufficient clue to Doxygen to don't bother with them for the
> output.
> 
> So, is there currently any way to leave out un-documented default
> constructors and destructors?

(Sorry for the lengthy quoting, I just wanted to rehash the problems
for the developers, as the mails were sent to the -users list.)

Now, I have a patch done by a colleague (Kristian Eide) which fixes
both problems, so please consider the following for inclusion (done
against the code of the 1.2.17 release):

----8<--- [snip] --------8<--- [snip] --------8<--- [snip] ----8<----

--- memberdef.cpp	Wed Jun 26 19:16:23 2002
+++ ../../doxygen-1.2.17/src/memberdef.cpp	Mon Aug 12 12:11:13 2002
@@ -581,8 +581,33 @@
                              mtype==Friend
                             );
     
+    // hide member if it overrides a member in a superclass and has no
+    // documentation
+    bool visibleIfDocVirtual = (reimplements() == NULL ||
+                                hasDocumentation()
+                               );
+
+    // true if this member is a constructor or destructor
+    // This should perhaps be included in the MemberDef class
+    bool cOrDTor = (name()==classDef->localName() ||         // constructor
+                    (name().find('~')!=-1 &&  // hack to detect destructor
+                     name().find("operator")==-1
+                    )
+                   );
+
+    // hide default constructors or destructors (no args) without
+    // documentation
+    bool visibleIfNotDefaultCDTor = !(cOrDTor &&
+                                     defArgList != NULL &&
+                                     (defArgList->isEmpty() ||
+                                      defArgList->first()->type == "void"
+                                     ) &&
+                                     !hasDocumentation()
+                                    );
+
     bool visible = visibleIfStatic && visibleIfDocumented && 
-                   visibleIfEnabled && visibleIfPrivate && !annScope;
+                   visibleIfEnabled && visibleIfPrivate &&
+                   visibleIfDocVirtual && visibleIfNotDefaultCDTor && !annScope;
     //printf("MemberDef::isBriefSectionVisible() %d\n",visible);
     return visible;
 }

----8<--- [snip] --------8<--- [snip] --------8<--- [snip] ----8<----

Best regards,
Morten

[Doxygen-develop] [PATCH] Fix for Doxygen warning on private members

[Morten E. <mo...@si...>]

Hi,

I reported a problem last week about Doxygen spitting out warnings
about missing documentation for private members in certain cases. The
particular case I was seeing is when you hide a "friend class"
statement inside the private block of a C++ class declaration, like
this:

  ---8<--- [snip] -------8<--- [snip] -------8<-
  class MyClass {
     // [...]

  private:
    friend class MyHiddenImplementationClass;
  };
  ---8<--- [snip] -------8<--- [snip] -------8<-

..then Doxygen will complain about missing doc on
MyHiddenImplementationClass, even though EXTRACT_PRIVATE=NO.

Here's a patch from my colleague Kristian Eide that will take care of
the problem:

--- memberdef.cpp	Tue Aug 13 10:05:39 2002
+++ ../../doxygen-1.2.17/src/memberdef.cpp	Tue Aug 13 09:57:34 2002
@@ -1519,7 +1519,8 @@
     t="file", d=fd;
 
   if (d && d->isLinkable() && !isLinkable() && !isDocumentedFriendClass()
-      && name().find('@')==-1)
+      && name().find('@')==-1 &&
+      (prot!=Private || Config_getBool("EXTRACT_PRIVATE")))
    warn_undoc(m_defFileName,m_defLine,"Warning: Member %s of %s %s is not documented.",
         name().data(),t,d->name().data());
 }


Best regards,
Morten

Re: [Doxygen-develop] Re: [Doxygen-users] Avoiding repeated documentation on inherited members?

[Morten E. <mo...@si...>]

* Morten
> So, is there any way to accomplish this -- ie don't include
> overridden methods in the output _if_ they just use the doc of the
> same method in the superclass?

* Dimitri
> INHERIT_DOCS = NO should do that if I understand you correctly.

That's what I thought too from reading the Doxygen documentation, but
there are two major inconveniences of how that works:

        - the inherited/overridden methods are *still* present in the
          output, but only for the class reference summary at the top
          (which I would still like to avoid to have minimal clutter
          for the application programmer who's using the library API)

        - Doxygen suddenly spews out a zillion warnings for all the
          undocumented, inherited/overridden methods

(Actually, there doesn't seem to be any real advantage to using
INHERIT_DOCS=NO in any setting..? Is this perhaps because the
drawbacks mentioned above are bugs?)

Best regards,
Morten

[Doxygen-develop] Have a look at the project related to UML diagrams through dot to ol

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

Hi,

Stefan Seefeld (the competing Synopsis project) posted
the following reference to the Synopsis mailing list:

  http://www.spinellis.gr/sw/umlgraph/

The UMLGraph project by Diomidis D. Spinellis is written
in Java for JavaDoc and the dot tool (about 10KB of source 
text).  It is freely available, but copyrighted.  It probably
should be recorded in doxygen todo list.  I guess that
some users really wish to have UML diagrams generated
by doxygen.

Regards,
  Petr

-- 
Petr Prikryl, Skil, spol. s r.o., (pri...@sk...)

[Doxygen-develop] Re: [Doxygen-users] Avoiding repeated documentation on inherited members?

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

On Wed, Aug 07, 2002 at 10:02:25AM +0200, Morten Eriksen wrote:
> Hi,
> 
> I wondering if it's possible to configure Doxygen to _not_ repeat the
> documentation on C++ inherited members of subclasses?
> 
> IMHO, this feature tends to clutter up the API documentation more than
> it clarifies -- at least for the particular class library I'm
> documenting.
> 
> An example to make myself clear:
> 
> ----8<--- [snip] ---------8<--- [snip] ---------8<--- [snip] -----
> 
> //! This class blablabla...
> class Super {
> public:
>         //! This method blablabla...
>         virtual void aVirtualMethod(void);
> };
> 
> //! This class blablabla...
> class Sub : class Super {
> public:
>         virtual void aVirtualMethod(void);
> };
> 
> ----8<--- [snip] ---------8<--- [snip] ---------8<--- [snip] -----
> 
> Now, for class Sub, aVirtualMethod() will be included in the
> documentation, just repeating the documentation of this method in the
> Super class. I would like to avoid that, to "clean up" and remove
> unnecessary clutter in a huge, fine-grained class library I have
> documented here. This library has deeply nested class inheritance
> hierarchies, with many virtual methods like that above primarily used
> internally in the library implementation. Having the method
> documentation repeated for each subclass which overrides the virtual
> method of the superclass therefore just generates "noise".
> 
> So, is there any way to accomplish this -- ie don't include overridden
> methods in the output _if_ they just use the doc of the same method in
> the superclass?

INHERIT_DOCS = NO should do that if I understand you correctly.

Regards,
  Dimitri

Re: [Doxygen-develop] Visual C++ 6, the latest CVS release, and CodeWarrior integration

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

On Tue, Aug 06, 2002 at 12:01:23PM +0100, Simon Goodwin wrote:
> Hi Doxygenators,
> 
> I just got the new CVS release and tried to compile it with VC++6
> on Windoze2k, and got the following error messages when I ran the
> make.bat script:
> 
> c:\dev\doxygen-1.2.17\src\ce_parse.cpp(337) : error C2620: union 'yyalloc' : member 'yyvs' has user-defined constructor or non-trivial default constructor
> c:\dev\doxygen-1.2.17\src\ce_parse.cpp(784) : error C2039: 'yyvs' : is not a member of 'yyalloc'
>         c:\dev\doxygen-1.2.17\src\ce_parse.cpp(335) : see declaration of 'yyalloc'
> 
> I worked around this by copying that source file from the
> previous doxygen release:
> 
> cp ../doxygen-1.2.16/src/ce_parse.cpp src/ce_parse.cpp

From the manual:

Bison problems 

"
Versions 1.31 to 1.34 of bison contain a "bug" that results in 
a compiler errors like this: 

ce_parse.cpp:348: member `class CPPValue yyalloc::yyvs' with 
constructor not allowed in union 

This problem has been solved in version 1.35 
(versions before 1.31 will also work). 
"

i.e. time to upgrade bison.

> This got it to build from the command line. I don't know if I have
> broken anything by doing so but it seems superficially OK. Maybe
> a flex/bison devotee can explain what's going on? The ce_parse.cpp
> file is being generated automagically. It's also possible that the 
> 'problem' is in Risible (sic) C++6. Has anyone else tried this recently?
> 
> In any case,  I needed to add the following to the project file to get 
> it to build from the VC++6 IDE:
> 
> src\docparser.cpp
> src\docparser.h
> src\doctokeniser.h
> src\doctokeniser.cpp
> src\cmdmapper.cpp
> src\cmdmapper.h

For completeness could you please also include:
  src\docvisitor.h
  src\printdocvisitor.h

> I attach an updated DSP file which encapsulates these additions. Note
> that you still need to run 'make msvc' once from the command line
> before the IDE build will work. That's because VC++6 does not know
> how to parse the flex and bison files that generate some of the C source
> that needs to be compiled (and I don't know how to tell it to do so ;-). 
> Once you've run that make once, you can build variants from the IDE 
> as long as you have not changed any of the flex and bison data files.
> 
> Cheers
> 
> Simon Goodwin
> Technology Programmer, ATD
> 
> P.S. if any of you have to use or support Metrowerks's CodeWarrior you
> may like to know a way to integrate Doxygenated helpfile documentation
> into their IDE (similar to the MSDNIntegrator for DevStudio - I have had
> no replies to my request for an equivalent for VC++7 (aka .NET), sadly).

Maybe not too many people are already using VC++ for various reasons 
(I am one those people). Nice to see you are working on CodeWarrior support
though.

Regards,
  Dimitri

[Doxygen-develop] Visual C++ 6, the latest CVS release, and CodeWarrior integration

[Simon G. <sim...@at...>]

Hi Doxygenators,

I just got the new CVS release and tried to compile it with VC++6
on Windoze2k, and got the following error messages when I ran the
make.bat script:

c:\dev\doxygen-1.2.17\src\ce_parse.cpp(337) : error C2620: union 'yyalloc' : member 'yyvs' has user-defined constructor or non-trivial default constructor
c:\dev\doxygen-1.2.17\src\ce_parse.cpp(784) : error C2039: 'yyvs' : is not a member of 'yyalloc'
        c:\dev\doxygen-1.2.17\src\ce_parse.cpp(335) : see declaration of 'yyalloc'

I worked around this by copying that source file from the
previous doxygen release:

cp ../doxygen-1.2.16/src/ce_parse.cpp src/ce_parse.cpp

This got it to build from the command line. I don't know if I have
broken anything by doing so but it seems superficially OK. Maybe
a flex/bison devotee can explain what's going on? The ce_parse.cpp
file is being generated automagically. It's also possible that the 
'problem' is in Risible (sic) C++6. Has anyone else tried this recently?

In any case,  I needed to add the following to the project file to get 
it to build from the VC++6 IDE:

src\docparser.cpp
src\docparser.h
src\doctokeniser.h
src\doctokeniser.cpp
src\cmdmapper.cpp
src\cmdmapper.h

I attach an updated DSP file which encapsulates these additions. Note
that you still need to run 'make msvc' once from the command line
before the IDE build will work. That's because VC++6 does not know
how to parse the flex and bison files that generate some of the C source
that needs to be compiled (and I don't know how to tell it to do so ;-). 
Once you've run that make once, you can build variants from the IDE 
as long as you have not changed any of the flex and bison data files.

Cheers

Simon Goodwin
Technology Programmer, ATD

P.S. if any of you have to use or support Metrowerks's CodeWarrior you
may like to know a way to integrate Doxygenated helpfile documentation
into their IDE (similar to the MSDNIntegrator for DevStudio - I have had
no replies to my request for an equivalent for VC++7 (aka .NET), sadly).

We have just persuaded Metrowerks to add support for third-party helpfiles
and although it is not part of the release yet, it does work and we (ATD and
Metrowerks) are looking for testers. Contact me if you'd like to know more.

-- 
Simon Goodwin <sim...@at...>

[Doxygen-develop] Italian translation update

[Alessandro F. <ale...@da...>]

Here is the intalian translation updated to include the new trDeprecatedList
method.

Cheers
Alessandro

[Doxygen-develop] [PATCH] Debug-version of Doxygen for Linux with g++

[Morten E. <mo...@si...>]

Hi,

attached is a tiny patch for the tmake configuration file for the
Linux/g++ combo. It causes debugging information to actually be
included in the executables.

(Is this mailinglist the correct place to send patches?)

Regards,
Morten

--- doxygen-1.2.17-org/tmake/lib/linux-g++/tmake.conf	Sat Aug 18 19:09:39 2001
+++ doxygen-1.2.17/tmake/lib/linux-g++/tmake.conf	Wed Jul 31 15:13:08 2002
@@ -38,7 +38,7 @@
 TMAKE_LINK_SHLIB	= g++
 TMAKE_LFLAGS		=
 TMAKE_LFLAGS_RELEASE	=
-TMAKE_LFLAGS_DEBUG	=
+TMAKE_LFLAGS_DEBUG	= -g
 TMAKE_LFLAGS_SHLIB	= -shared
 TMAKE_LFLAGS_SONAME	= -Wl,-soname,
 

[Doxygen-develop] [BUG] "friend class" causes error in "Friends" section

[Morten E. <mo...@si...>]

Hi,

I think this is a bug in the C++ parsing: when using "friend class
SomeClass" in a header file, like this

---8<---- [snip] --------8<---- [snip] --------8<---- [snip] -----
class MyClass {
private:
  friend class SomeClass;
};
---8<---- [snip] --------8<---- [snip] --------8<---- [snip] -----

..then "class SomeClass" shows up in the "Friends" section of
MyClass's class documentation. If I understand the purpose of the
"Friends" section correctly, it is supposed to only contain a list of
friend _functions_.

A friend _class_ is a completely different thing, and is something
that should only be of interest for the implementation -- ie it's a
detail that should not be present in the class doc.

(Also, Doxygen spits a bogus warning when hitting "friend class
SomeClass": "Warning: Member SomeClass of class MyClass is not
documented.")

I found this problem when upgrading from 1.2.something to 1.2.15, and
it is still present in 1.2.17.

Regards,
Morten

[Doxygen-develop] Updated Portuguese Translation

[Rui L. <rui...@ya...>]

Hellos,

I've attached an updated Portuguese translation.


I would appreciate that the maintainer of the
Internationalization page
(http://www.stack.nl/~dimitri/doxygen/langhowto.html#langhowto)
could change my email from rui...@NO...
to ru...@NO.... Thanks.


----
Rui Lopes


__________________________________________________
Do You Yahoo!?
Yahoo! Health - Feel better, live better
http://health.yahoo.com

[Doxygen-develop] New Brazilian Portuguese Translator

[FJTC (F. J. T. Chino) <ch...@ic...>]

Hi.

Here goes the updated version of Brazilian Portuguese translator.


See you...
FJTC

----------------------------------------------------------------------
         FJTC (Fabio Jun Takada Chino) - ch...@ic...
      Computer Science - ICMC - University of Sao Paulo - Brazil
              GBDI - Grupo de Base de Dados e Imagens
----------------------------------------------------------------------
Homepage
  http://www.icmc.sc.usp.br/~chino (main)
  http://gbdi.icmc.sc.usp.br/ (GBDI)
  http://www.fjtc.hpg.com.br/ (Anime - Portuguese Only)
  http://www.bbits.hpg.com.br/ (Game Programming - English Only)
======================================================================

[Doxygen-develop] [BUG?] \internal keyword in C++ causing warning

[Morten E. <mo...@si...>]

Hi,

not sure if this is a bug or just a policy change, but using the
"\internal" keyword on methods, like this:

------8<---- [snip] -----------8<---- [snip] -----------8<----

class MyClass {
public:
  void myfunc(void);
};

/*!
  \class MyClass
  Dummy doc.
*/

/*!
  \internal
 */
void
MyClass::myfunc(void)
{
}

------8<---- [snip] -----------8<---- [snip] -----------8<----

..now causes Doxygen to spit out a warning:

<...>/internal_keyword.cpp:3: Warning: Member myfunc of class MyClass is not documented.

(Tested with a configuration file with all defaults (except INPUTS)
and with the latest release 1.2.17.)

This is not the way Doxygen used to behave, I believe it started
spewing out warnings on this from 1.2.15 and onwards. Policy change or
a bug?

If this is a policy change, is there a way to turn off this behavior?
Getting warnings on "\internal" makes it difficult (or rather
impossible) to see the _real_ warnings when Doxygenizing large
projects.

Regards,
Morten

[Doxygen-develop] [BUG] Parse error with C++ operator overriding

[Morten E. <mo...@si...>]

Hi,

another annoying little buglet:

----8<--- [snip] ---------8<--- [snip] ---------8<--- [snip] -----

class MyClass {
public:
  MyClass operator -(void) const;
};

/*!
  \class MyClass
  Dummy doc.
*/

/*!
  test
 */
MyClass
MyClass::operator-(void) const
{
  return MyClass();
}

----8<--- [snip] ---------8<--- [snip] ---------8<--- [snip] -----

This causes doxygen to emit:

<...>/minus_operator.cpp:16: Warning: member `operator-' of class `MyClass' cannot be found
<...>/minus_operator.cpp:3: Warning: Member operator - of class MyClass is not documented.

If the space between "operator" and "-" in the class declaration is
removed, it works as expected.

Overriding other built-in operators in the same manner causes the same
error (ie it's not related specifically to the "-" character).

Regards,
Morten

[Doxygen-develop] [BUG] Private classes/structs

[Morten E. <mo...@si...>]

Hi,

I have an annoying problem with Doxygen (tested with released version
1.2.17). This declaration in a .h file:

----8<---- [snip] ---------8<---- [snip] ---------8<---- [snip] -----

class MyClass {
private:
  struct ShouldNotBeDocumented {
  };
};

----8<---- [snip] ---------8<---- [snip] ---------8<---- [snip] -----

..will cause doxygen to emit the following warning:

<...>/private_struct.h:3: Warning: Compound MyClass::ShouldNotBeDocumented is not documented.

(With a configuration file with only default values.)

This seems like a bug to me, as the default value of EXTRACT_PRIVATE
is "NO"?

BTW, is this mailinglist the best place to report bugs, or should I
rather mail them directly to Dimitri?

Regards,
Morten

[Doxygen-develop] Slovak language update

[Stanislav K. <sk...@po...>]

I've just finished slovak language translator update to version 1.2.17.=20
The implementation of method trDeprecatedList() is also included.

Stan
=0A____________________________________=0Ahttp://www.pobox.sk/ - urcujeme t=
rendy=0A

[Doxygen-develop] RE: Attention! - Croatian translations update

[Boris B. <bor...@zg...>]

Hi,

>Hi,
>
>If you are a language maintainer, then you should know
>that 1.2.17-20020728 adds new translator method trDeprecatedList(). It
should be implemented (very easy) inside your language translator to
have the up-to-
>date status again.

>Thanks,
>  Petr

>-- 
>Petr Prikryl, Skil, spol. s r.o., (pri...@sk...)


Here's updated Croatian translation

--
Boris

[Doxygen-develop] Attention! New method added to Translator class...

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

Hi,

If you are a language maintainer, then you should know
that 1.2.17-20020728 adds new translator method trDeprecatedList().
It should be implemented (very easy) inside your language
translator to have the up-to-date status again.

Thanks,
  Petr

-- 
Petr Prikryl, Skil, spol. s r.o., (pri...@sk...)

Re: [Doxygen-develop] Lint for Doxygen

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

On Fri, Jul 26, 2002 at 04:31:40PM +0100, Simon Goodwin wrote:
> Hello Doxygenators,
> 
> Having documented quite a lot of things with Doxygen now I find that I and others
> consistently make mistakes that are not reported by the document parser. Before
> I encourage all the other programmers at ATD to use Doxygen - and I have to sort
> out all their mistakes - I want to extend our documentation toolchain to spot and
> report as many errors as possible. At the moment it takes several passes of running
> Doxygen, examining the log, editing the headers, and round again to get everything
> documented - and even then there tend to be hidden mark-up errors that only surface
> when the document gets read by a human.
> 
> I am aware that this is not easy and not something that can be 100% comprehensive.
> There is also a risk that spurious errors may be reported, and so I would like to make this
> checking optional, at least at first, despite the creeping featuritus evident from the long
> list of Doxygen options already. ;-)
> 
> My experience of compiler-writing is that writing a compiler for correct source is
> easy compared with writing one that gives good diagnostics when incorrect
> source is supplied - perhaps because of the free-form source, C compilers don't
> seem to try to do this very hard - which is a pity as more incorrect programs are
> submitted for compilation than correct ones (or your makefile is broken). But even
> if we can't catch every error of imaginative programmers, it would be both friendly and
> convenient for all concerned to put some effort into reporting common errors.
> 
> The first thing I want to do is ask if others reckon this would be a useful extension
> to Doxygen, however it might be implemented.

I recognise the problem of errors in the documentation blocks not being
detected and resulting in broken output. In fact I'm currently completely 
rewriting the way documentation is handled! I've started to write a 
recursive decent parser for documentation blocks (which builds an abstract 
syntax tree, instead of just doing only some lexical scanning as is done now).
This is quite a huge effort and it will take some time before it will appear
in doxygen's base line, however what I have now looks quite promissing already
(this is actually my third attempt, the other two were less successful ;-).

> Then I'd like to know what errors are worth checking for. After that we can try to categorise
> the errors and work out if it is worth checking for them inside Doxygen, in a separate program
> (hence the Lint reference) or by mixing the trick.
> 
> I welcome suggestions about implementing this. I favour the idea of extending Doxygen itself
> or using Gnu tools to minimise the need for new code, but if there's anything already around
> that does such a job, I'd like to hear of it.
> 
> But the first thing to do is to list the problems that I've often seen and which seem worth sifting
> out.
> 
> 
> Things to check for in a Lint for Doxygen
> =========================
> 
> // ! or //* ! instead of //! and /*! (etc.) 
> 
> //<! instead of //!< and equivalents.

These would not be detected by the new documentation parser, but could
be detected in an earlier pass.

> commands with / instead of \ at the start.
> 
> Unmatched or mismatched HTML brackets. 
> 
> &entity without following semicolon.
> 
> \ followed by an illegal character (probably should be \\)
> 

These are all be catchable by the new parser.

> More than two documentation blocks before an entity (only the last two are
> parsed, earlier ones are ignored).

Doxygen does produce a warning when it ignores documentation blocks already.

> ---------------------------------
> 
> I'm sure there are others. Comments welcome. :-)

Yes, please report common errors you see.

Regards,
  Dimitri

[Doxygen-develop] Lint for Doxygen

[Simon G. <sim...@at...>]

Hello Doxygenators,

Having documented quite a lot of things with Doxygen now I find that I and others
consistently make mistakes that are not reported by the document parser. Before
I encourage all the other programmers at ATD to use Doxygen - and I have to sort
out all their mistakes - I want to extend our documentation toolchain to spot and
report as many errors as possible. At the moment it takes several passes of running
Doxygen, examining the log, editing the headers, and round again to get everything
documented - and even then there tend to be hidden mark-up errors that only surface
when the document gets read by a human.

I am aware that this is not easy and not something that can be 100% comprehensive.
There is also a risk that spurious errors may be reported, and so I would like to make this
checking optional, at least at first, despite the creeping featuritus evident from the long
list of Doxygen options already. ;-)

My experience of compiler-writing is that writing a compiler for correct source is
easy compared with writing one that gives good diagnostics when incorrect
source is supplied - perhaps because of the free-form source, C compilers don't
seem to try to do this very hard - which is a pity as more incorrect programs are
submitted for compilation than correct ones (or your makefile is broken). But even
if we can't catch every error of imaginative programmers, it would be both friendly and
convenient for all concerned to put some effort into reporting common errors.

The first thing I want to do is ask if others reckon this would be a useful extension
to Doxygen, however it might be implemented.

Then I'd like to know what errors are worth checking for. After that we can try to categorise
the errors and work out if it is worth checking for them inside Doxygen, in a separate program
(hence the Lint reference) or by mixing the trick.

I welcome suggestions about implementing this. I favour the idea of extending Doxygen itself
or using Gnu tools to minimise the need for new code, but if there's anything already around
that does such a job, I'd like to hear of it.

But the first thing to do is to list the problems that I've often seen and which seem worth sifting
out.


Things to check for in a Lint for Doxygen
=========================

// ! or //* ! instead of //! and /*! (etc.) 

//<! instead of //!< and equivalents.

commands with / instead of \ at the start.

Unmatched or mismatched HTML brackets. 

&entity without following semicolon.

\ followed by an illegal character (probably should be \\)

More than two documentation blocks before an entity (only the last two are
parsed, earlier ones are ignored).

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

I'm sure there are others. Comments welcome. :-)

Simon Goodwin, Technology Programmer, Attention to Detail Ltd.

-- 
Simon Goodwin <sim...@at...