Support automatic type deduction, attributes, documenting template parameters

[gnzlbg]

Example code (copy paste into a header file and launch cldoc on it, works as is):

#include <type_traits>

// @return size of a list
[[deprecated]] static constexpr auto size() {}

// @return size of a list
static constexpr auto size2() { return std::size_t{1}; }

// @return size of parameter pack <Ts>
//
// @Ts parameter pack
template<class... Ts>
static constexpr auto size3(Ts...) { return sizeof...(Ts); }

// Foo function
// @T some type
// @arg some argument
//
// body
//
// @return calls <T>{}() or <arg>()
template<class T>
static constexpr auto foo(T arg) { return arg(); }


// Always returns 2
//
// @return always 2
int bar() { return 2; }

Produces the following output:

Functions

foo (T arg)
Foo function
T
arg
return

• the documentation for T, arg, and return breaks.
• The return type is missing (auto). A note saying that the return type cannot be inferred would be awesome.
• static constexpr is missing from the documentation

size3 (Ts)
@return size of parameter pack
Ts
return

• same as above, but return seems to work, still linking Ts... to the template parameter breaks :/
• note that here the return type will always be the same! it should be documented as auto, but a note saying something like: auto (_always_ std::size_t) would be awesome.

size()
@return size of a list
return

• attributes are omitted from the documentation
• it should be nice if @[[attribute]] could be used to document the reason of a given attribute
• here return type is always void, this should be documented like auto (_always_ void)

int
bar ( )
Always returns 2
return
always 2

• here the return type is in, but when the return is documented the type is not mentioned, IMO:
  return [int] always 2 as generated documentation is better, types are an important part of the interface

size2()
@return size of a list
return

• here the function is documented only with // @return size of a list, this goes to the brief description, but not to the documentation of the return,