Simplified signatures in generated documentation

[Jacob Carlborg via Digitalmars-d]

Looking at the documentation for std.algorithm and the std.logger 
(currently under review) [1] I think the function signatures look 
absolutely horrible. The functions std.algorithm in have complicated 
template constraints and in std.logger there are many functions with 
default arguments like "int line = __LINE__".

Using "ditto" to combine the documentation of multiple symbols with 
different template constraints spanning multiple lines doesn't make it 
easier to see what signature belongs to which symbol.

I was thinking if it would be a good idea to implement some form of 
automatically simplified signatures for Ddoc. Examples of simplifying 
the signatures could be:

* Remove parameters with default arguments where the values are special 
symbols like __LINE__ and __FILE__. Most of the time the user doesn't 
need to pass these and therefore doesn't need to know about them

* Remove template constraints. I think, at least with std.algorithm, 
it's mostly obvious what to pass and I rarely need to look at the 
constraints

The simplified signatures would be show for the main signatures, i.e. 
the ones with a light blue background, and the full signatures would be 
added at the end of the documentation for each symbol.

We could also have a special Ddoc macro, that is recognized by the 
compiler, which allows to manually specify the simplified signature.

What do you think?

[1] http://burner.github.io/phobos/phobos-prerelease/std_logger_core.html

-- 
/Jacob Carlborg