doxygen-users

[Doxygen-users] Doyxgen 1.2.7: \ingroup group1 group2 still allowed?

[Patrick O. <Pat...@pa...>]

Hi all!

According to the documentation (and implementation) of
\ingroup an entity may be put into several different
groups at once.

However, later on in groupdef.cpp:addMemberToGroups()
this is detected and triggers a warning (groupdef.cpp, line 617):

  Member ... found in multiple groups.!
  The member will be put in group ..., and not group ...

The class MemberDef also allows to set only one GroupDef: 
    setGroupDef(GroupDef *gd)        { group=gd; }

Are \ingroup and related mechanisms with more than one
group per entity deprecated? 

If you ask me, then I'd be more than happy when each
entity can only be in one group and I'd volunteer to
clean up the implementation: 

- Entry::groups doesn't have to be a list.
- An explicit \ingroup overrides an implicit @{ @}.
- A \defgroup @{ @} in one place overrides an \addtogroup @{ @}
  in another place (e.g. header files uses \defgroup, C files use
  \addtogroup) - this is currently impossible to implement, but
  something that I have been missing for quite a while.

Bye, Patrick
-- 
// pallas  GmbH  ............  Patrick Ohly  .............
   Hermuelheimer Str. 10       Software-Engineer
   D-50321 Bruehl, Germany     po...@pa...
   fax +49-(0)2232-1896-29     phone  +49-(0)2232-1896-30 
   http://www.pallas.com 
..........................................................

[Doxygen-users] Re: Doyxgen 1.2.7: \ingroup group1 group2 still allowed?

[Guntram B. <be...@Ma...>]

Patrick Ohly wrote:
Patrick Ohly wrote:

>=20
> If you ask me, then I'd be more than happy when each
> entity can only be in one group and I'd volunteer to
> clean up the implementation:

I think it can make sense to have one entity in several
groups, and would therefore strongly advocate that this
will remain an option.
I could however imagine a config option which triggers warnings
if an entity is in several groups, in circumstances where this
is considered an error.

cheers
--guntram


--=20
------------------------------------------------------------------
Dr. Guntram Berti            | voice: ++49 +355 69 37 17
                             | fax  : ++49 +355 69 24 02
LS  Numerische Mathematik &  | be...@ma...
 Wissenschaftliches Rechnen  | http://www.math.tu-cottbus.de/~berti
Institut f=FCr Mathematik      |                     =20
BTU Cottbus                  | R 313,                  O__ =20
Universit=E4tsplatz 3-4        | Lehrgeb=E4ude 1          c/ /'_
D-03044 Cottbus              |                       (*) \(*)=20
------------------------------------------------------------------

Re: [Doxygen-users] Doyxgen 1.2.7: \ingroup group1 group2 still allowed?

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

On Fri, May 04, 2001 at 03:12:54PM +0200, Patrick Ohly wrote:
> Hi all!
> 
> According to the documentation (and implementation) of
> \ingroup an entity may be put into several different
> groups at once.

Yes, but...

> 
> However, later on in groupdef.cpp:addMemberToGroups()
> this is detected and triggers a warning (groupdef.cpp, line 617):
> 
>   Member ... found in multiple groups.!
>   The member will be put in group ..., and not group ...
> 
> The class MemberDef also allows to set only one GroupDef: 
>     setGroupDef(GroupDef *gd)        { group=gd; }

... members are an exception. Anything else can be in multiple groups.

> Are \ingroup and related mechanisms with more than one
> group per entity deprecated? 

No, but for members there is a slight problem.
Currently, a member is identified by its container and a local label
unique within the container (in html: a file and an anchor). 

Now suppose a member is in two groups and we want to (auto)link to it.
Where should the link go to?

A clean solution would be to link to the natural container of the
member (i.e. for a global function link to the file, for a class
member link to the class), regardless of any artifical group the 
member was put in.

But then what if someone wants its documentation to consist just of
the items that he/she grouped by hand? This would lead to ambigious
links targets in case the member is in multiple groups.

> If you ask me, then I'd be more than happy when each
> entity can only be in one group and I'd volunteer to
> clean up the implementation: 
> 
> - Entry::groups doesn't have to be a list.

It still does for entries that do not represent members.

> - An explicit \ingroup overrides an implicit @{ @}.

That would make sense.

> - A \defgroup @{ @} in one place overrides an \addtogroup @{ @}
>   in another place (e.g. header files uses \defgroup, C files use
>   \addtogroup) - this is currently impossible to implement, but
>   something that I have been missing for quite a while.

Well if it is impossible to implement, then feel free to try
the impossible :-)

Regards,
  Dimitri

Re: [Doxygen-users] Doyxgen 1.2.7: \ingroup group1 group2 still allowed?

[Patrick O. <Pat...@pa...>]

On Fri, May 04, 2001 at 10:21:28PM +0200, Dimitri van Heesch wrote:
> On Fri, May 04, 2001 at 03:12:54PM +0200, Patrick Ohly wrote:
> > Hi all!
> > 
> > According to the documentation (and implementation) of
> > \ingroup an entity may be put into several different
> > groups at once.
> 
> Yes, but...
> 
> > 
> > However, later on in groupdef.cpp:addMemberToGroups()
> > this is detected and triggers a warning (groupdef.cpp, line 617):
> > 
> >   Member ... found in multiple groups.!
> >   The member will be put in group ..., and not group ...
> > 
> > The class MemberDef also allows to set only one GroupDef: 
> >     setGroupDef(GroupDef *gd)        { group=gd; }
> 
> ... members are an exception. Anything else can be in multiple groups.

So the comment "Add a member to all groups it is contained in" for
groupdef.cpp:addMemberToGroups() is not accurate, is it? Only one
group is possible.

Anyway, now I understand the problem.

> > - A \defgroup @{ @} in one place overrides an \addtogroup @{ @}
> >   in another place (e.g. header files uses \defgroup, C files use
> >   \addtogroup) - this is currently impossible to implement, but
> >   something that I have been missing for quite a while.
> 
> Well if it is impossible to implement, then feel free to try
> the impossible :-)

I will ;-) Of course it's not impossible, but requires more
information than currently available for an Entry: for each
entry in Entry::groups addMemberToGroups() needs to know where
the definition came from to resolve the conflict.

I guess I will change Entry::groups to a list of pairs of
group name and a definition where the group name came from
(\ingroup, @{ @}, member group). Okay?

BTW, does it make sense to put members of structures into groups?

/**
 *  Test class
 *  \ingroup Group1 Group2
 */
struct test {
    /**
     * \ingroup Group1
     * test a
     */
    int a;
};

This works, but then Group1 is said to contain a variable a, which is
described as test::a. Okay, I guess if someone really wants to do that
with \ingroup then he should be able to do so. However, the same
thing happens with

/** \defgroup Group1 First Group
 */
/*@{*/

/** Test class
 *  \ingroup Group1 Group2
 */
struct test {
    /**
     * test a
     */
    int a;
};

/*@}*/

The automatic grouping is applied to test::a, which is probably regarded
as a bug and not a feature by most, isn't it?

One more thing: may I change \addtogroup so that it doesn't require
a \defgroup, but might create the group itself? The reason is that in
our documentation there is no unique place where we could use \defgroup,
so I'd rather like to use \addtogroup everywhere and let doxygen sort
it all out. The current semantic of \addtogroup wouldn't be changed,
only extended by allowing an optional group title.

Bye, Patrick
-- 
// pallas  GmbH  ............  Patrick Ohly  .............
   Hermuelheimer Str. 10       Software-Engineer
   D-50321 Bruehl, Germany     po...@pa...
   fax +49-(0)2232-1896-29     phone  +49-(0)2232-1896-30 
   http://www.pallas.com 
..........................................................

Re: [Doxygen-users] Doyxgen 1.2.7: \ingroup group1 group2 still allowed?

[Ronald v. E. <eij...@iq...>]

SGkgQWxsLA0KDQpJZiBwZW9wbGUgc3RhcnQgd29ya2luZyBvbiBncm91cHMgaG93IGFib3V0IGFs
bG93aW5nIHRoZSAvaW5ncm91cCB0byBiZSB1c2VkIHRvIGdyb3VwIG1ldGhvZHMgdG9nZXRoZXIg
Zm9yIGEgY2xhc3MuIFRoaXMgaXMgbm93IHBvc3NpYmxlIHVzaW5nIEB7IEB9IGJ1dCB0aGlzIHJl
cXVpcmVzIHRoYXQgZ3JvdXAgbWVtYmVycyBhcmUgZ3JvdXBlZCBpbiB0aGUgaGVhZGVyIGZpbGVz
IGFzd2VsbC4gSW4gb3VyIHByb2plY3Qgd2Ugd2FudCB0byBrZWVwIGFsbCB0aGUgZG94eWdlbiBp
bmZvcm1hdGlvbiBpbiB0aGUgY3BwIGZpbGVzLiANCg0KQyd5YSwNCg0KICAgIFJvbmFsZA0K

Re: [Doxygen-users] Doyxgen 1.2.7: \ingroup group1 group2 still allowed?

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

On Mon, May 07, 2001 at 09:58:23AM +0200, Patrick Ohly wrote:
> On Fri, May 04, 2001 at 10:21:28PM +0200, Dimitri van Heesch wrote:
> > On Fri, May 04, 2001 at 03:12:54PM +0200, Patrick Ohly wrote:
> > > Hi all!
> > > 
> > > According to the documentation (and implementation) of
> > > \ingroup an entity may be put into several different
> > > groups at once.
> > 
> > Yes, but...
> > 
> > > 
> > > However, later on in groupdef.cpp:addMemberToGroups()
> > > this is detected and triggers a warning (groupdef.cpp, line 617):
> > > 
> > >   Member ... found in multiple groups.!
> > >   The member will be put in group ..., and not group ...
> > > 
> > > The class MemberDef also allows to set only one GroupDef: 
> > >     setGroupDef(GroupDef *gd)        { group=gd; }
> > 
> > ... members are an exception. Anything else can be in multiple groups.
> 
> So the comment "Add a member to all groups it is contained in" for
> groupdef.cpp:addMemberToGroups() is not accurate, is it? Only one
> group is possible.

Yes, that's correct. I've given this some thought and here is 
how I see it now:

A member (object of class MemberDef) should have exactly 
one "container" (a class derived from Definition, excluding 
MemberDef) to which autolinks will point. 

Normally (e.g. without user defined groups) the container is
the "natural" container to which the member belongs
(for a global function declared in a header file and defined in a 
source file "natural" it is already a bit ambiguous but anyway...).
If a member is put in a group and the natural container is
hidden, then the group will become the autolink container.

This way it is possible for a member to be in multiple groups,
and this will make autolinking easier as well, since a member
has all the information to generate the link.

> 
> Anyway, now I understand the problem.
> 
> > > - A \defgroup @{ @} in one place overrides an \addtogroup @{ @}
> > >   in another place (e.g. header files uses \defgroup, C files use
> > >   \addtogroup) - this is currently impossible to implement, but
> > >   something that I have been missing for quite a while.
> > 
> > Well if it is impossible to implement, then feel free to try
> > the impossible :-)
> 
> I will ;-) Of course it's not impossible, but requires more
> information than currently available for an Entry: for each
> entry in Entry::groups addMemberToGroups() needs to know where
> the definition came from to resolve the conflict.
> 
> I guess I will change Entry::groups to a list of pairs of
> group name and a definition where the group name came from
> (\ingroup, @{ @}, member group). Okay?

Yes, that would do I guess.

> 
> BTW, does it make sense to put members of structures into groups?
> 
> /**
>  *  Test class
>  *  \ingroup Group1 Group2
>  */
> struct test {
>     /**
>      * \ingroup Group1
>      * test a
>      */
>     int a;
> };
> 
> This works, but then Group1 is said to contain a variable a, which is
> described as test::a. Okay, I guess if someone really wants to do that
> with \ingroup then he should be able to do so. However, the same
> thing happens with
> 
> /** \defgroup Group1 First Group
>  */
> /*@{*/
> 
> /** Test class
>  *  \ingroup Group1 Group2
>  */
> struct test {
>     /**
>      * test a
>      */
>     int a;
> };
> 
> /*@}*/
> 
> The automatic grouping is applied to test::a, which is probably regarded
> as a bug and not a feature by most, isn't it?

Yes, this is a bug indeed. I was trying to make it possible to
group a variable of an anonymous struct like:

struct
{
  int x;
  int y;
} point;

The bug was introduced as a side-effect of this. 
You can fix this by uncommenting the context rebuild code in 
parseCompounds in scanner.l. Here is the relevant fragment:

      gstat = FALSE;
      virt = Normal;

      memberGroupId = NOGROUP;

      // rebuild compound's group context 
      //QCString *s = ce->groups->first();
      //if (s)
      //{
      // lastDefGroup=*s;
      //        startGroup();
      //}

      //current->mGrpId = memberGroupId = ce->mGrpId;

      scanYYlex() ;
      delete current; current=0;
      ce->program.resize(0);

Anyway, this shows that things have become rather 
complex (well at least to complex for me to understand :-).
So doxygen need restructuring. I have to spend some more 
time on this. 

I've already started to change the way information is stored 
in doxygen. Currently all classes and namespaces are stored as 
flat lists. By keeping the original structure many things should 
become simpler, but this does not yet directly help with the
above problems.

> One more thing: may I change \addtogroup so that it doesn't require
> a \defgroup, but might create the group itself? The reason is that in
> our documentation there is no unique place where we could use \defgroup,
> so I'd rather like to use \addtogroup everywhere and let doxygen sort
> it all out. The current semantic of \addtogroup wouldn't be changed,
> only extended by allowing an optional group title.

I don't have problems with that, as long as it also works like it does now.

Regards,
  Dimitri

Re: [Doxygen-users] Doyxgen 1.2.7: \ingroup group1 group2 still allowed?

[Patrick O. <Pat...@pa...>]

On Mon, May 07, 2001 at 08:28:30PM +0200, Dimitri van Heesch wrote:
> A member (object of class MemberDef) should have exactly 
> one "container" (a class derived from Definition, excluding 
> MemberDef) to which autolinks will point. 
> 
> Normally (e.g. without user defined groups) the container is
> the "natural" container to which the member belongs
> (for a global function declared in a header file and defined in a 
> source file "natural" it is already a bit ambiguous but anyway...).
> If a member is put in a group and the natural container is
> hidden, then the group will become the autolink container.

This is something I haven't thought of yet, but I'll tryto get
it working.

> > The automatic grouping is applied to test::a, which is probably regarded
> > as a bug and not a feature by most, isn't it?
> 
> Yes, this is a bug indeed. I was trying to make it possible to
> group a variable of an anonymous struct like:
> 
> struct
> {
>   int x;
>   int y;
> } point;
> 
> The bug was introduced as a side-effect of this. 
> You can fix this by uncommenting the context rebuild code in 
> parseCompounds in scanner.l.

I had found that one already - I guess that means there is some
hope that I'll get it right ;-)

> Here is the relevant fragment:
> 
>       gstat = FALSE;
>       virt = Normal;
> 
>       memberGroupId = NOGROUP;
> 
>       // rebuild compound's group context 
>       //QCString *s = ce->groups->first();
>       //if (s)
>       //{
>       // lastDefGroup=*s;
>       //        startGroup();
>       //}
> 
>       //current->mGrpId = memberGroupId = ce->mGrpId;

Are you sure about not setting mGrpId? I hadn't removed that
one, but I haven't tested any member groups either.

Bye, Patrick
-- 
// pallas  GmbH  ............  Patrick Ohly  .............
   Hermuelheimer Str. 10       Software-Engineer
   D-50321 Bruehl, Germany     po...@pa...
   fax +49-(0)2232-1896-29     phone  +49-(0)2232-1896-30 
   http://www.pallas.com 
..........................................................