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
