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/