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

Jacob Carlborg:

> 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.

Another possible improvement is to add popups that show the complete type when the mouse is over the name of a type or value.

You can see that used in this F# code:
http://tomasp.net/blog/2014/puzzling-fsharp/

And in this near-Haskell code:
http://goto.ucsd.edu/~rjhala/liquid/haskell/blog/blog/2014/08/15/a-finer-filter.lhs/

Bye,
bearophile

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

On Wednesday, 20 August 2014 at 07:04:50 UTC, Jacob Carlborg wrote:
> * 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

BTW aren't they a bit over-complicated?

(args.length == 0 || (args.length > 0 && !is(Unqual!(A[0]) : bool)))

isn't length unsigned?
so in the or-part args.length > 0 is obviously true and superflouos.

(args.length == 0 || !is(Unqual!(A[0]) : bool))

is at least a little more readable...

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

> 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.

I like it. Some of my code also features a lot of free functions with template constraints and it does get a bit much.

Related remark on the other side of things (more text!): documentation is currently lacking UDA annotations [1] and I would love it if that were to be added at some point.

[1] https://issues.dlang.org/show_bug.cgi?id=12995

On 20/08/14 09:35, bearophile wrote:

> Another possible improvement is to add popups that show the complete
> type when the mouse is over the name of a type or value.
>
> You can see that used in this F# code:
> http://tomasp.net/blog/2014/puzzling-fsharp/
>
> And in this near-Haskell code:
> http://goto.ucsd.edu/~rjhala/liquid/haskell/blog/blog/2014/08/15/a-finer-filter.lhs/

Yeah. Scala also uses simplified signatures for some of their methods [1]. They have a section last in the documentation for each symbol that can be expanded to show the full signature. This is actually where I got the idea. Although I haven't been able to find the source code for the documentation so I don't know if it's manually specified. I'm suspecting that because it's only available for very few methods.


[1] http://www.scala-lang.org/api/current/#scala.collection.immutable.HashMap filter on "toArray".

-- 
/Jacob Carlborg

On 20/08/14 10:20, Paulo Pinto wrote:

> I think this is important when discussion about language complexity, as
> the discussions in the Scala community show.

Scala has simplified signatures for a few methods as well, see: http://forum.dlang.org/thread/lt1hai$186b$1@digitalmars.com#post-lt1mkd:241cqo:241:40digitalmars.com

-- 
/Jacob Carlborg

On Wed, Aug 20, 2014 at 09:04:49AM +0200, 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__".

Yeah, the problem is that ddoc treats the entire declaration as a single unit... it really should break it down into the return type, the function name, compile-time arguments, runtime arguments, attributes, template constraints, followed by pre/post conditions. Each of these should be their own macro so that the formatting of each part can be customized. Right now it's just one gigantic amorphous blob which is frightening to behold.


> 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.

If ddoc could treat each part of the declaration separately, I think it would help a lot. E.g., you could indent the sig constraints so that it's visually obvious which declaration it belongs to.


> 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

No, I want to see all parameters in the docs. Otherwise I might inadvertently write a new overload that conflicts with the hidden default arguments. I think the root of the problem here is that ddoc currently doesn't let you format each parameter individually within the declaration -- it has macros for formatting type names and parameter names, but nothing for customizing the entire parameter as a unit. If we had that, we could, for example, tabulate each parameter on its own line, or in multiple columns, which would make it much more readable.


> * 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

I disagree. Before template constraints were shown, the complaint was that ddoc produced identical declarations for multiple overloads, and it's unclear which overload applied to which argument types. IMO the real problem is one of presentation, not content. All constraints should be shown, but their formatting should be much more customizable than they currently are. Again, there is currently no way to control formatting for individual clauses in the sig constraint; it's just treated as a single amorphous blob. If ddoc would allow customization of the sig constraint as a unit, and within that unit the formatting of each clause, then it could be formatted in a much more readable way.


> 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.
[...]

If we had more control over the formatting of each element in the declaration (instead of being handed the whole thing as an amorphous blob with only the keywords/identifier formatting being customizable), we could implement ddoc macros to achieve these things without needing to build them into the compiler.

Basically, the formatting of declarations need to be more structured. Currently we can only format the entire giant declaration as a unit, and individual type names and identifiers, but nothing in between. Adding more structure would help with the problem:

$(DECLARATION ...)		// entire declaration
	$(RETURNTYPE ...)	// return type
	$(DECLIDENT ...)	// identifier
	$(CTPARAMS ...)		// compile-time parameters
	$(RTPARAMS ...)		// runtime parameters
		$(PARAM ...)	// single parameter
			$(PARAMSTORAGE ...)	// storage class
			$(PARAMTYPE ...)	// parameter type
			$(PARAMIDENT ...)	// parameter identifier
			$(PARAMDEF ...)		// default value
	$(SIGCONSTRAINTS ...)	// entire signature constraint
		$(CONSTRAINTCLAUSE ...)		// individual clause in constraint

If we had such a structure, then we could, for example, use Javascript on the documentation page to collapse parameter types / sig constraints, and have buttons for the reader to expand them at will.


T

-- 
Marketing: the art of convincing people to pay for what they didn't need before which you can't deliver after.

On 2014-08-20 16:59, H. S. Teoh via Digitalmars-d wrote:

> No, I want to see all parameters in the docs.

If it was unclear, all parameters will be available in the full signature that is available in the generated docs as well.

> I disagree.

See above

> If we had more control over the formatting of each element in the
> declaration (instead of being handed the whole thing as an amorphous
> blob with only the keywords/identifier formatting being customizable),
> we could implement ddoc macros to achieve these things without needing
> to build them into the compiler.
>
> Basically, the formatting of declarations need to be more structured.
> Currently we can only format the entire giant declaration as a unit,
> and individual type names and identifiers, but nothing in between.
> Adding more structure would help with the problem:
>
> $(DECLARATION ...)		// entire declaration
> 	$(RETURNTYPE ...)	// return type
> 	$(DECLIDENT ...)	// identifier
> 	$(CTPARAMS ...)		// compile-time parameters
> 	$(RTPARAMS ...)		// runtime parameters
> 		$(PARAM ...)	// single parameter
> 			$(PARAMSTORAGE ...)	// storage class
> 			$(PARAMTYPE ...)	// parameter type
> 			$(PARAMIDENT ...)	// parameter identifier
> 			$(PARAMDEF ...)		// default value
> 	$(SIGCONSTRAINTS ...)	// entire signature constraint
> 		$(CONSTRAINTCLAUSE ...)		// individual clause in constraint
>
> If we had such a structure, then we could, for example, use Javascript
> on the documentation page to collapse parameter types / sig constraints,
> and have buttons for the reader to expand them at will.

I really hope I don't have to write that manually. I was thinking of a more simple solution. In the places you see the signature currently you will see the simplified signature. Then a new section is added with the full signature. This all happens automatically. No information is lost, it's just moved.

-- 
/Jacob Carlborg