doxygen-develop

[Doxygen-develop] new feature discussion

[Antoine T. <at...@ko...>]

Hello, I would like to discuss about some new options(features) for
doxygen.
All of them are triggered by the configuration file.

So I introduce them by there configuration name.

1 - NO_TYPEDEF_REFERENCED_BY_RELATION
Just don't produce the "Referenced by" paragraph for typedef.
Most of the time, this paragraph is long and useless.
There is no "reference by" for classes... so why for typedef.

The patch is very simple :
Just add a condition in the function addDocCrossReference
static void addDocCrossReference(MemberDef *src,MemberDef *dst)
{
  //printf("addDocCrossReference
src=%s,dst=%s\n",src->name().data(),dst->name().data());
  if ( dst->isTypedef() &&
Config_getBool("NO_TYPEDEF_REFERENCED_BY_RELATION") ) //+++ added line
    return;
//+++ added line
  if (Config_getBool("REFERENCED_BY_RELATION") && 
      (src->isFunction() || src->isSlot()) 
     )
  {
    dst->addSourceReferencedBy(src);
  }
  if ((Config_getBool("REFERENCES_RELATION") ||
Config_getBool("CALL_GRAPH")) && 
      (src->isFunction() || src->isSlot())
     )
  {
    src->addSourceReferences(dst);
  }
}

2 - GROUP_COLLABORATION_GRAPH
Create a dot graph on the top of each group page.
The graph shows relations between groups :
- is the group is part of an other group
- is the group contains other groups
- all members (class, namespace ...) share with other groups

3 - ALLOW_MEMBER_MULTIGROUP
This change the behavior of group pages.
With this option set, group page don't contain member documentation but
only a link to the member documentation.
With this option set, a function can be part of more than one groups.
With this option set, function documentation are no more moved to the
group page, so for a class member, the documentation stays in the class
file...

4 - SHOW_GROUPLINKS
Just add in the documentation of members a link to the group(s) they are
part of. (like for classes)

Please tell me what you think about those features.
Keep in mind that they don't change anything if the options are not set.

All of those 4 features are independent, but 2 and 4 are more relevant
with the 3 set.

Thanks

Re: [Doxygen-develop] new feature discussion

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

On Tue, 7 Dec 2004 18:29:13 +0100, Antoine Tandin
<at...@ko...> wrote:
> Hello, I would like to discuss about some new options(features) for
> doxygen.
> All of them are triggered by the configuration file.
> 
> So I introduce them by there configuration name.
> 
> 1 - NO_TYPEDEF_REFERENCED_BY_RELATION
> Just don't produce the "Referenced by" paragraph for typedef.
> Most of the time, this paragraph is long and useless.
> There is no "reference by" for classes... so why for typedef.

I agree, but I don't think is it needed to have an option for this:
just always turn this on.
 
> The patch is very simple :
> Just add a condition in the function addDocCrossReference

> 
> 2 - GROUP_COLLABORATION_GRAPH
> Create a dot graph on the top of each group page.
> The graph shows relations between groups :
> - is the group is part of an other group
> - is the group contains other groups
> - all members (class, namespace ...) share with other groups

This could be useful, but how are you going to express to containment relations.
A "boxes in boxes" approach (which would be natural) doesn't work well with dot.

> 3 - ALLOW_MEMBER_MULTIGROUP
> This change the behavior of group pages.
> With this option set, group page don't contain member documentation but
> only a link to the member documentation.
> With this option set, a function can be part of more than one groups.
> With this option set, function documentation are no more moved to the
> group page, so for a class member, the documentation stays in the class
> file...

This feature has been discussed and requested before, but I don't think it
will work with the current implementation. If you have an undocumented file
with a member in multiple groups and this member is referred to in some place
to which group would you point? (if the file that actually contains
the member was
documented, the file could be a good candidate, but this is not guaranteed. 

> 
> 4 - SHOW_GROUPLINKS
> Just add in the documentation of members a link to the group(s) they are
> part of. (like for classes)

This could be useful (but less so if the member can be in one group only).

Regards,
  Dimitri

RE : [Doxygen-develop] new feature discussion

[Antoine T. <at...@ko...>]

diff file attached for an implementation of those 4 features. Critics
are welcome :)

Following an example in compiled html.

-----Message d'origine-----
De=A0: Antoine Tandin [mailto:at...@ko...]=20
Envoy=E9=A0: mardi 7 d=E9cembre 2004 18:29
=C0=A0: dox...@li...
Objet=A0: [Doxygen-develop] new feature discussion

Hello, I would like to discuss about some new options(features) for
doxygen.
All of them are triggered by the configuration file.

So I introduce them by there configuration name.

1 - NO_TYPEDEF_REFERENCED_BY_RELATION
Just don't produce the "Referenced by" paragraph for typedef.
Most of the time, this paragraph is long and useless.
There is no "reference by" for classes... so why for typedef.

The patch is very simple :
Just add a condition in the function addDocCrossReference
static void addDocCrossReference(MemberDef *src,MemberDef *dst)
{
  //printf("addDocCrossReference
src=3D%s,dst=3D%s\n",src->name().data(),dst->name().data());
  if ( dst->isTypedef() &&
Config_getBool("NO_TYPEDEF_REFERENCED_BY_RELATION") ) //+++ added line
    return;
//+++ added line
  if (Config_getBool("REFERENCED_BY_RELATION") &&=20
      (src->isFunction() || src->isSlot())=20
     )
  {
    dst->addSourceReferencedBy(src);
  }
  if ((Config_getBool("REFERENCES_RELATION") ||
Config_getBool("CALL_GRAPH")) &&=20
      (src->isFunction() || src->isSlot())
     )
  {
    src->addSourceReferences(dst);
  }
}

2 - GROUP_COLLABORATION_GRAPH
Create a dot graph on the top of each group page.
The graph shows relations between groups :
- is the group is part of an other group
- is the group contains other groups
- all members (class, namespace ...) share with other groups

3 - ALLOW_MEMBER_MULTIGROUP
This change the behavior of group pages.
With this option set, group page don't contain member documentation but
only a link to the member documentation.
With this option set, a function can be part of more than one groups.
With this option set, function documentation are no more moved to the
group page, so for a class member, the documentation stays in the class
file...

4 - SHOW_GROUPLINKS
Just add in the documentation of members a link to the group(s) they are
part of. (like for classes)

Please tell me what you think about those features.
Keep in mind that they don't change anything if the options are not set.

All of those 4 features are independent, but 2 and 4 are more relevant
with the 3 set.

Thanks



-------------------------------------------------------
SF email is sponsored by - The IT Product Guide
Read honest & candid reviews on hundreds of IT Products from real users.
Discover which products truly live up to the hype. Start reading now.=20
http://productguide.itmanagersjournal.com/
_______________________________________________
Doxygen-develop mailing list
Dox...@li...
https://lists.sourceforge.net/lists/listinfo/doxygen-develop

Re: RE : [Doxygen-develop] new feature discussion

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

On Fri, 10 Dec 2004 10:41:50 +0100, Antoine Tandin
<at...@ko...> wrote:
> diff file attached for an implementation of those 4 features. Critics
> are welcome :)

I would like to discuss the usefulness of the group graphs (now this
is added and
people can try).

I think it is not too useful to have edges for elements that are in
multiple groups.
Any opions about this are welcome.

When I think about groups I can think of three types of graphs that I
think could be
useful:
1) A graph showing the containment relations between groups. This is basically
     a simplified version from what is available now.
2) A graph showing all classes in a group and their relations (both
inheritance and
     using relations).
3) A graph showing all files in a group and their #include dependency relations.

Depending on the group any of the 3 types of graphs could provide
useful information.

Let me know what you think about this idea.

Regards,
  Dimitri

RE : RE : [Doxygen-develop] new feature discussion

[Antoine T. <at...@ko...>]

Of course showing group dependencies is a great feature.
I would like to have this feature (I'm ready to code it:))

But I think doing only one big graph showing all relations/dependencies
of groups will very nice but probably unreadable, so useless.

This is why I started with the group collaboration graph.
The aim of this graph is to show "dependencies" created by the way the
code is documented.
This graph show only explicit relations between groups : means
"ingroup"... commands only.

For example, from doxygen, we can create some of those groups :
- Group Dot : groups about dot features stuff. Contains dot.h dot.cpp
... classes in those files...
- Group HTML Output : everything about html feature. Contains htmlgen.h,
htmlhelp.h, htmlattrib.h ...,default css file..., htmlgen class ...
- Group LATEX : same as html
- Group MAN : same as html
- Group Ouputgen : everything about exporting doxygen doc. Contain files
... outputgen class... and of course contains groups HTML, LATEX, MAN
...

In "htmlgen class", the function "startDotGraph" is specialized for
exporting a dot graph for html format.=20
So it is relevant to explicitly put the function in the "Dot" group and
the "htlm ouput" group.
Same for "latexgen" BUT not for "mangen" because there is no dot output
for man pages (even if the function exist, it does nothing).

The group collaboration graph will show that Dot feature is in relation
with HTML and LATEX features (and by deduction outputgen) by the
functions "startDotGraph".
The graph will not show link with Dot and MAN, this is good because
there is no relevant link.


Now let's create a graph using real code dependencies.
You will see more relations between Dot and outputgen groups because of
implementation (like outputlist::startDotGraph) and you will also see a
link between Dot and MAN because the empty function
mangen::startDotGraph is called.
In an other hand, in this kind of graph, you can't see shared data file
between group, because the "code" is not aware of that.

So I think those 2 kind of graph have 2 different purpose :
- the first shows the "design" dependencies : that is why I called id
"collaboration graph"
- the second shows the "implementation" dependencies : I would use the
term "dependency" for this kind of graph.

Once again the "implementation dependency" can be very heavy.
So I think it is better to split it into more lighten specialized graphs
like : include and file dependency (your point 3), class inheritance and
relation dependencies(your point 2), and the function call dependencies
(using refby stuff).

Even spitted, those graph will most of the time quite "heavy".
If you have some framework group (like QT stuff for instance: qt list,
qtstream..., or file sytem, memory, thread...) those groups will always
appear in the graphs, because those groups are used everywhere in the
code.
It mean every group dependencies graph of you project will have most of
the time a "minimum" number elements.

I think this is not a problem, because the aim of those graph is not to
be "easy to read" but to point out all real direct or indirect
dependencies.


For all of those class of graph, it could be very useful to have one big
graph which plays with all groups.
Like done for class hierarchy and collaboration graph.
Means one big :
- groups "collaboration" graph
- groups "call dependencies" graph
- groups "include and file dependencies" graph
- groups "class dependencies" graph

Regards

-----Message d'origine-----
De=A0: Dimitri van Heesch [mailto:do...@gm...]=20
Envoy=E9=A0: lundi 13 d=E9cembre 2004 20:35
=C0=A0: Antoine Tandin
Cc=A0: dox...@li...
Objet=A0: Re: RE : [Doxygen-develop] new feature discussion

On Fri, 10 Dec 2004 10:41:50 +0100, Antoine Tandin
<at...@ko...> wrote:
> diff file attached for an implementation of those 4 features. Critics
> are welcome :)

I would like to discuss the usefulness of the group graphs (now this
is added and
people can try).

I think it is not too useful to have edges for elements that are in
multiple groups.
Any opions about this are welcome.

When I think about groups I can think of three types of graphs that I
think could be
useful:
1) A graph showing the containment relations between groups. This is
basically
     a simplified version from what is available now.
2) A graph showing all classes in a group and their relations (both
inheritance and
     using relations).
3) A graph showing all files in a group and their #include dependency
relations.

Depending on the group any of the 3 types of graphs could provide
useful information.

Let me know what you think about this idea.

Regards,
  Dimitri


-------------------------------------------------------
SF email is sponsored by - The IT Product Guide
Read honest & candid reviews on hundreds of IT Products from real users.
Discover which products truly live up to the hype. Start reading now.=20
http://productguide.itmanagersjournal.com/
_______________________________________________
Doxygen-develop mailing list
Dox...@li...
https://lists.sourceforge.net/lists/listinfo/doxygen-develop

Re: RE : RE : [Doxygen-develop] new feature discussion

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

On Wed, 15 Dec 2004 12:32:55 +0100, Antoine Tandin
<at...@ko...> wrote:
> Of course showing group dependencies is a great feature.
> I would like to have this feature (I'm ready to code it:))
> 
> But I think doing only one big graph showing all relations/dependencies
> of groups will very nice but probably unreadable, so useless.
> 

Maybe I wasn't very clear, but I meant to have a class collaboration diagram
showing ONLY those classes that are in the SAME group (a box per class and
edges for the relations with other classes in the same group). Unless 
someone puts all classes in one group (which doesn't make too much sense),
the diagram will only a small number of boxes and edges. Same idea applies 
for files.

> This is why I started with the group collaboration graph.
> The aim of this graph is to show "dependencies" created by the way the
> code is documented.
> This graph show only explicit relations between groups : means
> "ingroup"... commands only.

This is indeed a valid graph of its own, but I do not think relation between
classes, etc that are in multiple groups need to be shown (they are now).

> For example, from doxygen, we can create some of those groups :
> - Group Dot : groups about dot features stuff. Contains dot.h dot.cpp
> ... classes in those files...
> - Group HTML Output : everything about html feature. Contains htmlgen.h,
> htmlhelp.h, htmlattrib.h ...,default css file..., htmlgen class ...
> - Group LATEX : same as html
> - Group MAN : same as html
> - Group Ouputgen : everything about exporting doxygen doc. Contain files
> ... outputgen class... and of course contains groups HTML, LATEX, MAN
> ...
> 
> In "htmlgen class", the function "startDotGraph" is specialized for
> exporting a dot graph for html format.
> So it is relevant to explicitly put the function in the "Dot" group and
> the "htlm ouput" group.
> Same for "latexgen" BUT not for "mangen" because there is no dot output
> for man pages (even if the function exist, it does nothing).
> 
> The group collaboration graph will show that Dot feature is in relation
> with HTML and LATEX features (and by deduction outputgen) by the
> functions "startDotGraph".
> The graph will not show link with Dot and MAN, this is good because
> there is no relevant link.
> 
> Now let's create a graph using real code dependencies.
> You will see more relations between Dot and outputgen groups because of
> implementation (like outputlist::startDotGraph) and you will also see a
> link between Dot and MAN because the empty function
> mangen::startDotGraph is called.
> In an other hand, in this kind of graph, you can't see shared data file
> between group, because the "code" is not aware of that.
> 
> So I think those 2 kind of graph have 2 different purpose :
> - the first shows the "design" dependencies : that is why I called id
> "collaboration graph"
> - the second shows the "implementation" dependencies : I would use the
> term "dependency" for this kind of graph.

I think I understand what you mean. Problem is that everyone seems to
have a different idea what a collaboration graph is (in UML it is again
something else). 

I agree it would be useful to have a way to just mention a couple of 
classes (or files, dirs, groups,...) and that doxygen produces a image 
with just those classes (...) and their relations. Maybe the relations 
can also be user defined, but then it is pretty close to what is already 
possible with \dot .. \enddot.
 
> Once again the "implementation dependency" can be very heavy.
> So I think it is better to split it into more lighten specialized graphs
> like : include and file dependency (your point 3), class inheritance and
> relation dependencies(your point 2), and the function call dependencies
> (using refby stuff).
> 
> Even spitted, those graph will most of the time quite "heavy".
> If you have some framework group (like QT stuff for instance: qt list,
> qtstream..., or file sytem, memory, thread...) those groups will always
> appear in the graphs, because those groups are used everywhere in the
> code.
> It mean every group dependencies graph of you project will have most of
> the time a "minimum" number elements.

Not if you exclude any classes that are not in the group.

Regards,
  Dimitri