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