Simplified signatures in generated documentation

[Martin Drasar via Digitalmars-d]

On 20.8.2014 9:04, Jacob Carlborg via Digitalmars-d wrote:
> 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
> 

I think it is a good idea. I wanted to check on std.logger after that
torrent of changes and found that ddoc for memLogunctions template has
3633 characters and takes entire page for me. If you look carefully, it
gets quite clear, but for anyone coming from outside it would be a
massive deterrent.

Removing the parameters with default values and template constraints
made it about 1/3 in size, so a definite improvement.

If it was possible to somehow compress these lines:
.Logger.memLogFunctions!cast(LogLevel)cast(ubyte)32u.logImpl
that gets repeated for each alias that would be also great, because it
adds a lot to a line noise. However, I can't imagaine how...

Anyway +1 for both default params and template constraints.

Martin