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.


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.


 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