Simplified signatures in generated documentation

Paulo Pinto via Digitalmars-d digitalmars-d at puremagic.com
Wed Aug 20 01:20:39 PDT 2014


On Wednesday, 20 August 2014 at 07:04:50 UTC, Jacob Carlborg 
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 this is important when discussion about language 
complexity, as the discussions in the Scala community show.

--
Paulo




More information about the Digitalmars-d mailing list