www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Simplified signatures in generated documentation

reply Jacob Carlborg <doob me.com> writes:
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
Aug 20 2014
next sibling parent reply "bearophile" <bearophileHUGS lycos.com> writes:
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
Aug 20 2014
parent Jacob Carlborg <doob me.com> writes:
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
Aug 20 2014
prev sibling next sibling parent Martin Drasar via Digitalmars-d <digitalmars-d puremagic.com> writes:
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
Aug 20 2014
prev sibling next sibling parent "Dominikus Dittes Scherkl" writes:
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...
Aug 20 2014
prev sibling next sibling parent reply "Paulo Pinto" <pjmlp progtools.org> writes:
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
Aug 20 2014
parent Jacob Carlborg <doob me.com> writes:
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
Aug 20 2014
prev sibling next sibling parent "Stefan Frijters" <sfrijters gmail.com> writes:
 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
Aug 20 2014
prev sibling parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
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.
Aug 20 2014
parent reply Jacob Carlborg <doob me.com> writes:
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
Aug 20 2014
parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Wed, Aug 20, 2014 at 06:15:39PM +0200, Jacob Carlborg via Digitalmars-d
wrote:
 On 2014-08-20 16:59, H. S. Teoh via Digitalmars-d wrote:
[...]
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.
[...] Sorry, I didn't make myself clear. What I meant was that ddoc will generate the above structure, so that user ddoc templates can customize the appearance of each element in the declaration. You don't actually write any of these macros (except where you wish to customize the appearance of that part of the declaration); you write the function declaration as usual, and ddoc will internally expand them using the above structure. If one or more elements aren't defined, they default to just passing the text through verbatim. So essentially, it's about being able to target a specific part of the declaration to customize its formatting. T -- Let's call it an accidental feature. -- Larry Wall
Aug 20 2014
parent Jacob Carlborg <doob me.com> writes:
On 20/08/14 18:34, H. S. Teoh via Digitalmars-d wrote:

 Sorry, I didn't make myself clear. What I meant was that ddoc will
 generate the above structure, so that user ddoc templates can customize
 the appearance of each element in the declaration. You don't actually
 write any of these macros (except where you wish to customize the
 appearance of that part of the declaration); you write the function
 declaration as usual, and ddoc will internally expand them using the
 above structure.  If one or more elements aren't defined, they default
 to just passing the text through verbatim.  So essentially, it's about
 being able to target a specific part of the declaration to customize its
 formatting.
Ok, I see. Sounds like a good idea. -- /Jacob Carlborg
Aug 20 2014