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

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