Hello Doxygen users,
We use a filter to transform Perl classes documented with Doxygen into C++ code
that Doxygen understands. In Perl, method overloading (same name but different
argument types) is handled explicitly by the code by querying the number and/or
types of the passed-in arguments. However, for documentation purposes, The
Doxygen filter can produce multiple signatures for the same method. For
example, let's assume there's an open() method with two signatures, one taking
a filename string and another taking a file handle. It is good to document
those as separate methods and that is achieved by generating C++ code for
Doxygen that looks like this:
/** @fn ref<Writer> open( string filename )
*
* Opens the named file for writing. Also writes the file header text.
*
*/
ref<Writer> open( string filename );
/**
* @fn ref<Writer> open( filehandle fh )
*
* Associates the already opened filehandle to the Writer object.
* Also writes the file header text. If you wish to pass in @c STDOUT
* or @c STDERR, you need to do it as follows:
* @code
* $writer->open( \\*STDOUT<file:///\\*STDOUT> );
* @endcode
*
*/
ref<Writer> open( filehandle fh );
Now imagine that the Writer class inherits from a WriterBase class that defines
a default open() method without any arguments. In C++, that constitutes a
distinct method signature and an object of the derived Writer class thus has
access to 3 variants of the same overloaded method. However, in Perl only the
subroutine name is used to distinguish between methods, and thus the open()
method of the base class is hidden. So, we don't want the documentation for
the open() method from the base class to appear in the documentation for the
derived class when INLINE_INHERITED_MEMB set is to YES. We only want it to
appear if there is no method named "open" in the derived class. So basically,
although we want to be able to overload a method name within a class, we want
to use only the method name to determine if a method is visible to a derived
class. A method in the derived class should indicate that it is "Reimplemented
from <base_class_name>" if the same method name appears in one of the base
classes.
Is this somehow possible by using existing special commands or setting
(undocumented) configuration variables?
Although this might seem like a minor issue, this situation actually pops up
frequently for the "new" method, which is the de-facto name for the constructor
method in Perl. The new method frequently has different signatures at
different levels of the class hierarchy, but only the most-derived
implementation should appear in the documentation of derived classes (when
INLINE_INHERITED_MEMB is set to YES).
-----------------------------------------------------------------------------------
This email message is for the sole use of the intended recipient(s) and may
contain
confidential information. Any unauthorized review, use, disclosure or
distribution
is prohibited. If you are not the intended recipient, please contact the
sender by
reply email and destroy all copies of the original message.
-----------------------------------------------------------------------------------
------------------------------------------------------------------------------
Free Next-Gen Firewall Hardware Offer
Buy your Sophos next-gen firewall before the end March 2013
and get the hardware for free! Learn more.
http://p.sf.net/sfu/sophos-d2d-feb
_______________________________________________
Doxygen-users mailing list
Doxygen-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/doxygen-users
