doxygen-users

[Doxygen-users] Problem with Makros

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

Hi all,

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

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

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


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

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

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

Implemetation:
ULONG STDMETHODCALLTYPE CImpIAutoApplication::AddRef()

With this syntax it works fine.

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

Best regard
Michael Martini

[Doxygen-users] hide undocumented enum

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

Hi all,

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

configuration options are the following:

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

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

Best regard

David Gaumont

Re: [Doxygen-users] hide undocumented enum

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

I have observed a similar problem as David...

On Fri, 08 Jun 2001 15:18:21 +0200, dav...@ca... wrote:

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

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

I get undocumented #defines in the documentation (introduced somewhere
since 1.2.4 [I skipped 1.2.5 and 1.2.6, but 1.2.7, 1.2.8 and 1.2.8.1 all
have this bug]).

A similar problem (but already present in 1.2.4): some undocumented, but
initialized arrays appear in the output.

If still needed to reproduce, I could try to provide a stripped down
example.

Regards

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

Re: [Doxygen-users] hide undocumented enum

[Volker B. <boe...@we...>]

Hi all,

we see statements like this

[Peter Steiner]
> I get undocumented #defines in the documentation (introduced somewhere
> since 1.2.4 [I skipped 1.2.5 and 1.2.6, but 1.2.7, 1.2.8 and 1.2.8.1 all
> have this bug]).

quite often in the last months in this list and i've the impression
that they are still getting more. It seems as if most reported bugs
are features that were added in version XXX but disappeared again in
version XYZ.

This sounds as if there should be a regression test suite to protect
the great features that doxygen provides from disappearing
while adding further features. (As far as i can see no tests are part
of the doxygen sources.)

I have some experience with the great CppUnit test framework (see
http://sourceforge.net/projects/cppunit, a port of JUnit) but i think
it would be too much work to instrument doxygen with more or less
complete unit tests.

Another, simpler possibility would be a collection of input files and
approved output files to compare to with 'diff' each time a code
change is made. To automate these tests shell scripts or dedicated
tools like dejagnu could be used.

What do you think about doxygen & tests?

Volker
-- 
Volker Boerchers
boe...@we...

[Doxygen-users] Doxygen testing (was: hide undocumented enums)

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

On Mon, Jun 11, 2001 at 04:49:18PM +0200, Volker Boerchers wrote:
> Hi all,
> 
> we see statements like this
> 
> [Peter Steiner]
> > I get undocumented #defines in the documentation (introduced somewhere
> > since 1.2.4 [I skipped 1.2.5 and 1.2.6, but 1.2.7, 1.2.8 and 1.2.8.1 all
> > have this bug]).
> 
> quite often in the last months in this list and i've the impression
> that they are still getting more. It seems as if most reported bugs
> are features that were added in version XXX but disappeared again in
> version XYZ.

Most of these happen because 
1) I'm restructuring things and
2) Things are a quite fragile (this is many because of the loosly parsing
   using flex, which is both a good and a bad thing.)
3) I (can) only do limited testing.

> This sounds as if there should be a regression test suite to protect
> the great features that doxygen provides from disappearing
> while adding further features. (As far as i can see no tests are part
> of the doxygen sources.)

That would certainly be nice.

> I have some experience with the great CppUnit test framework (see
> http://sourceforge.net/projects/cppunit, a port of JUnit) but i think
> it would be too much work to instrument doxygen with more or less
> complete unit tests.
> 
> Another, simpler possibility would be a collection of input files and
> approved output files to compare to with 'diff' each time a code
> change is made. To automate these tests shell scripts or dedicated
> tools like dejagnu could be used.

I think this would make the tests rather fragile. If I tweak something
on the output (for instance use a table instead of a list somewhere) 
that would invalidate all tests. Another problem is how to verify that the
generated diagrams contain the correct information.

Maybe verification on the XML output level would be more robost, but
with the current XML output a lot of information would be missed.

So, any ideas are welcome!

Regards,
  Dimitri

Re: [Doxygen-users] Doxygen testing (was: hide undocumented enums)

[Jens-A. R. <fl...@un...>]

> Maybe verification on the XML output level would be more robost, but
> with the current XML output a lot of information would be missed.
>
> So, any ideas are welcome!

...and what about expanding the XML output?

It would help realizing the needs of a lot of of doxygen users.

Let it be the ones looking for more .css options or fancy design stuff,
the ones that need to add other (non doxygen) content, those who want to
add, drop, rearrange the output, or it would even help testing as you
suggested yourself. Everything could be done without touching the core
code and without the chance of messing up your code.

But I saw that letting XML become an intermediate format is on your todo
list with a rather high difficulty number. However, I guess it would
simplify a lot of things once established and the new modularity will
enable others to contribute more easily and help further development.

Jens

Re: [Doxygen-users] Doxygen testing (was: hide undocumented enums)

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

On Mon, 11 Jun 2001 21:22:43 +0200, Dimitri van Heesch wrote:

>> Another, simpler possibility would be a collection of input files and
>> approved output files to compare to with 'diff' each time a code
>> change is made. To automate these tests shell scripts or dedicated
>> tools like dejagnu could be used.

> I think this would make the tests rather fragile. If I tweak something
> on the output (for instance use a table instead of a list somewhere) 
> that would invalidate all tests. Another problem is how to verify that the
> generated diagrams contain the correct information.

When postprocessing the HTML files (perhaps with lynx or some other
tool) and thus extracting only the textual information, these diffs
could surely be made fairly robust. But I agree that basing on XML
sounds like a more optimal approach...

Regards

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