doxygen-users

[Doxygen-users] Documenting unnamed parameters and functions that return references to arrays

[Rennie d. <de...@cp...>]

Hello, all.

I am in the process of documenting a C++ application with doxygen, and
have two questions for which I have been unable to find answers:

1. What is the proper way to document unnamed parameters?
I have the following C++ function, which returns the number of elements
in an array:
>         template <typename T, std::size_t N>
>         static inline std::size_t
>         arraySize(T (&)[N])
>         {
>             return N;
>         }
Since the parameter to arraySize is never used, giving it a name would
result in a compiler warning.  However, without a name, I can't use
@param to assign documentation to it.

2. Is there any trick to make doxygen correctly parse the signatures of
methods that return references to arrays?
I have several methods with prototypes similar to this one:
> const char (&IpqPacket::getIndevName() const)[IFNAMSIZ]
It is a const method named "getIndevName" in a class named "IpqPacket"
which returns a reference to "const char[IFNAMSIZ]"; it's in a namespace
called "IPQ".  Doxygen misparses the prototype and outputs > const
IPQ::char (&IpqPacket::getIndevName() const)
This suggests that doxygen thinks that is a function called "char" in a
namespace called "IPQ" that returns a "const" and takes a parameter of
type "&IpqPacket::getIndevName()" called "const".

I am also having some problems with the scope resolution operator.  In
one place, I declare
> friend void ::SignalQueue_signalHandler(int, siginfo_t*, void*);=20
in a class named "SignalQueue" in a namespace called "LibWheel".
"SignalQueue_signalHandler" is a function in the global namespace; the
friend declaration won't compile without the scope resolution operator.
 However, doxygen interprets it as a function in the namespace (or
class?) "void" that returns a "friend":
> friend void::SignalQueue_signalHandler (int, siginfo_t *, void *)

Does anyone have any ideas on how to work around these?

Thanks,
Rennie deGraaf

Re: [Doxygen-users] Documenting unnamed parameters and functions that return references to arrays

[Gennaro P. <gen...@ya...>]

On Wed, 30 May 2007 16:17:50 -0600, Rennie deGraaf wrote:

>Hello, all.
>
>I am in the process of documenting a C++ application with doxygen, and
>have two questions for which I have been unable to find answers:
>
>1. What is the proper way to document unnamed parameters?
>I have the following C++ function, which returns the number of elements
>in an array:
>>         template <typename T, std::size_t N>
>>         static inline std::size_t
>>         arraySize(T (&)[N])
>>         {
>>             return N;
>>         }

Why the static keyword?

>Since the parameter to arraySize is never used, giving it a name would
>result in a compiler warning.  However, without a name, I can't use
>@param to assign documentation to it.

However you can add documentation anyway, no? The real problem IMHO is
that Doxygen will sometimes show the parameter declaration as "T &
[N]" :-( Just imagine about your other cases. (Of course any decently
knowledgeable C++ programmer will realize that the declaration is
wrong, but still...). Fortunately, none of us has to doxygenate
something like the following :-)

  // Warning: not tested, at a minimum expect typos
  namespace detail {

    template < std::size_t, typename >
    struct dimension_count;

    template < std::size_t dim, typename T, std::size_t n >
    struct dimension_count< dim, T[ n ] >
    {
        static const std::size_t value =
            dimension_count< dim - 1, T >::value;
    };

    template < typename T, std::size_t n >
    struct dimension_count< 0, T[ n ] >
    {
        static const std::size_t value = n;
    };

 }

 template < std::size_t dim, typename T, std::size_t n >
 char ( &dimension( T (&)[ n ] ) ) [
          detail::dimension_count< dim, T[ n ] >::value ];

 template< typename T, std::size_t n >
 char (& count_of( T (&)[ n ] ) )[ n ];

-- 
Gennaro Prota -- C++ Developer, For Hire
https://sourceforge.net/projects/breeze/