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

[Richard D. <Ri...@Da...>]

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:kai...@ex...] 
Sent: Monday, February 13, 2017 9:32 AM
To: Richard Damon <Ri...@da...>; dox...@li...
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:Ri...@Da...]
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:kai...@ex...]
Sent: Friday, February 10, 2017 8:49 AM
To: dox...@li...
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
Dox...@li...
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