How can I add documentation for an inherited member function, that isn't overridden in the derived lass?

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

How can I add documentation for an inherited member function, that isn't overridden in the derived lass?

Stefan Ludewig-2
Hi.



I have the following situation:
class Base
{
public:
    doFoo(void);
};

class Derived : public Base
{
public:
    doBar(void);
};



Now I have documented Base::doFoo() and Derived::doBar(), but I need to
also document Derived::doFoo() with a doc that differs from the of
Base::doFoo(), although Derived does not override the implementation of
doFoo().
Is this possible? If yes, how?

/* @fn Derived::doFoo() */ makes Doxygen complain that it can't find a
matching class member for doFoo() in Derived.



Kind regards,
Stefan.

--
--
Exit Games | +49 40 413 596 0

Executive Christof Wegmann, CTO
Trade Registry / Amtsgericht Hamburg, Germany HRB 85991

We Make Multiplayer Simple | www.photonengine.com

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, SlashDot.org! http://sdm.link/slashdot
_______________________________________________
Doxygen-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/doxygen-users
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: How can I add documentation for an inherited member function, that isn't overridden in the derived lass?

Stefan Ludewig-2
Hi Richard.

"I do wonder a bit, about why the Base::doFoo() needs a different
documentation when is it used as inherited by Derived."
Well, it's a client-server solution and the function to document is part
of the client code base. doFoo() closes the connection. Base just handles
the connection, while Derived adds logic about rooms that one can join and
leave when connected (multiple clients can interact with each other when
they are inside the same room). Now when a client closes the connection
while it is inside a room, then the server will also interpret that as
leaving the room.
So the doc of Derived::doFoo() needs to mention that closing the
connection also means leaving any currently joined room, while Base is not
even aware of the existence of rooms, so that Base::doFoo() should not
mention this, as not every class that derives from it does implement room
logic.

" One possible solution, is to create a real Derived::doFoo(), something
like:

   doFoo(void) { Base::doFoo(); }

This function should have zero cost, as it will be inlined and be exactly
like a call to Base::doFoo at the call site. Now it can be documented, as
it exists."
I hoped there was a way to add a different doc for the inherited function,
without the need to override it with a dummy-wrapper that has no purpose
at all aside from doc, as I feel that such dummy-functions pollute the
API.

My current approach is
#if _DOC
    doFoo(void);
#endif

With _DOC only getting defined by Doxygen and not by any project for any
compiler, but this feels like a workaround for a missing Doxygen feature
to me.

Kind regards,
Stefan.

-----Original Message-----
From: Richard Damon [mailto:[hidden email]]
Sent: Freitag, 10. Februar 2017 23:14
To: 'Stefan Ludewig'
Subject: RE: [Doxygen-users] How can I add documentation for an inherited
member function, that isn't overridden in the derived lass?

Your first problem is that there really isn't a Derived::doFoo, so there
are real reason that you can't document such a thing (technically, when
you say Derived::doFoo(), it is looking in the 'namespace' of Derived for
doFoo(), and find the inherited version lf Base::doFoo() )

I do wonder a bit, about why the Base::doFoo() needs a different
documentation when is it used as inherited by Derived.

One possible solution, is to create a real Derived::doFoo(), something
like:

   doFoo(void) { Base::doFoo(); }

This function should have zero cost, as it will be inlined and be exactly
like a call to Base::doFoo at the call site. Now it can be documented, as
it exists.

-----Original Message-----
From: Stefan Ludewig [mailto:[hidden email]]
Sent: Friday, February 10, 2017 8:49 AM
To: [hidden email]
Subject: [Doxygen-users] How can I add documentation for an inherited
member function, that isn't overridden in the derived lass?

Hi.



I have the following situation:
class Base
{
public:
    doFoo(void);
};

class Derived : public Base
{
public:
    doBar(void);
};



Now I have documented Base::doFoo() and Derived::doBar(), but I need to
also document Derived::doFoo() with a doc that differs from the of
Base::doFoo(), although Derived does not override the implementation of
doFoo().
Is this possible? If yes, how?

/* @fn Derived::doFoo() */ makes Doxygen complain that it can't find a
matching class member for doFoo() in Derived.



Kind regards,
Stefan.

--
--
Exit Games | +49 40 413 596 0

Executive Christof Wegmann, CTO
Trade Registry / Amtsgericht Hamburg, Germany HRB 85991

We Make Multiplayer Simple | www.photonengine.com

--------------------------------------------------------------------------
--
--
Check out the vibrant tech community on one of the world's most engaging
tech sites, SlashDot.org! http://sdm.link/slashdot
_______________________________________________
Doxygen-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/doxygen-users

--
--
Exit Games | +49 40 413 596 0

Executive Christof Wegmann, CTO
Trade Registry / Amtsgericht Hamburg, Germany HRB 85991

We Make Multiplayer Simple | www.photonengine.com

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, SlashDot.org! http://sdm.link/slashdot
_______________________________________________
Doxygen-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/doxygen-users
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: How can I add documentation for an inherited member function, that isn't overridden in the derived lass?

Richard Damon
The fundamental issue is you are wanting to document a function that really doesn't exist. (I personally use a DOXYGEN define to handle your conditional situation, _DOC is in the implementation namespace, so unless you are taking that responsibility, you shouldn't use it).

My feeling about what you are describing is feeling like Base::doFoo isn't being documented properly. It is apparently using another virtual function to provide a hook that provides this differing functionality. I see a couple ways to handle this:

1) Derived and Base are considered to be part of a single package, and this linkage is a private implementation detail. In this case Base DOES know about Derived (at a design level, if not a class level) so it makes sense to document the various behaviors of the full package in the documentation.

2) Derived and Base are considered to be different packages, and the virtual function may be an implementation detail (perhaps documented in an implementation documentation package). Here, since the linkage is hidden in implementation details, but Base::doFoo() knows that its behavior is dependent on derived behavior, it should mention this, and point to the derived documentation for more details. You want to do this by creating documentation for a non-existent Derived::doFoo(), but it could go into a section of the general class documentation (or we can make the override not non-existent).

3) As above, but we are willing to disclose the virtual function, in which case Base::doFoo() can reference that function, and the details for the derived class can put the documentation in that member function.

4) We can make the linkage function a documented part of the interface,  so the interaction between doFoo() and the implementFoo() function is fully documented, and Derived:implementFoo() will be documented with the behavior.

-----Original Message-----
From: Stefan Ludewig [mailto:[hidden email]]
Sent: Monday, February 13, 2017 9:32 AM
To: Richard Damon <[hidden email]>; [hidden email]
Subject: RE: [Doxygen-users] How can I add documentation for an inherited member function, that isn't overridden in the derived lass?

Hi Richard.

"I do wonder a bit, about why the Base::doFoo() needs a different documentation when is it used as inherited by Derived."
Well, it's a client-server solution and the function to document is part of the client code base. doFoo() closes the connection. Base just handles the connection, while Derived adds logic about rooms that one can join and leave when connected (multiple clients can interact with each other when they are inside the same room). Now when a client closes the connection while it is inside a room, then the server will also interpret that as leaving the room.
So the doc of Derived::doFoo() needs to mention that closing the connection also means leaving any currently joined room, while Base is not even aware of the existence of rooms, so that Base::doFoo() should not mention this, as not every class that derives from it does implement room logic.

" One possible solution, is to create a real Derived::doFoo(), something
like:

   doFoo(void) { Base::doFoo(); }

This function should have zero cost, as it will be inlined and be exactly like a call to Base::doFoo at the call site. Now it can be documented, as it exists."
I hoped there was a way to add a different doc for the inherited function, without the need to override it with a dummy-wrapper that has no purpose at all aside from doc, as I feel that such dummy-functions pollute the API.

My current approach is
#if _DOC
    doFoo(void);
#endif

With _DOC only getting defined by Doxygen and not by any project for any compiler, but this feels like a workaround for a missing Doxygen feature to me.

Kind regards,
Stefan.

-----Original Message-----
From: Richard Damon [mailto:[hidden email]]
Sent: Freitag, 10. Februar 2017 23:14
To: 'Stefan Ludewig'
Subject: RE: [Doxygen-users] How can I add documentation for an inherited member function, that isn't overridden in the derived lass?

Your first problem is that there really isn't a Derived::doFoo, so there are real reason that you can't document such a thing (technically, when you say Derived::doFoo(), it is looking in the 'namespace' of Derived for doFoo(), and find the inherited version lf Base::doFoo() )

I do wonder a bit, about why the Base::doFoo() needs a different documentation when is it used as inherited by Derived.

One possible solution, is to create a real Derived::doFoo(), something
like:

   doFoo(void) { Base::doFoo(); }

This function should have zero cost, as it will be inlined and be exactly like a call to Base::doFoo at the call site. Now it can be documented, as it exists.

-----Original Message-----
From: Stefan Ludewig [mailto:[hidden email]]
Sent: Friday, February 10, 2017 8:49 AM
To: [hidden email]
Subject: [Doxygen-users] How can I add documentation for an inherited member function, that isn't overridden in the derived lass?

Hi.



I have the following situation:
class Base
{
public:
    doFoo(void);
};

class Derived : public Base
{
public:
    doBar(void);
};



Now I have documented Base::doFoo() and Derived::doBar(), but I need to also document Derived::doFoo() with a doc that differs from the of Base::doFoo(), although Derived does not override the implementation of doFoo().
Is this possible? If yes, how?

/* @fn Derived::doFoo() */ makes Doxygen complain that it can't find a matching class member for doFoo() in Derived.



Kind regards,
Stefan.

--
--
Exit Games | +49 40 413 596 0

Executive Christof Wegmann, CTO
Trade Registry / Amtsgericht Hamburg, Germany HRB 85991

We Make Multiplayer Simple | www.photonengine.com

--------------------------------------------------------------------------
--
--
Check out the vibrant tech community on one of the world's most engaging tech sites, SlashDot.org! http://sdm.link/slashdot _______________________________________________
Doxygen-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/doxygen-users

--
--
Exit Games | +49 40 413 596 0

Executive Christof Wegmann, CTO
Trade Registry / Amtsgericht Hamburg, Germany HRB 85991

We Make Multiplayer Simple | www.photonengine.com


------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, SlashDot.org! http://sdm.link/slashdot
_______________________________________________
Doxygen-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/doxygen-users
Loading...