Simplified signatures in generated documentation

H. S. Teoh via Digitalmars-d digitalmars-d at puremagic.com
Wed Aug 20 07:59:06 PDT 2014


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.


More information about the Digitalmars-d mailing list