Simplified signatures in generated documentation

[H. S. Teoh via Digitalmars-d]

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