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