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
