I'm not sure if this should be flagged as a bug, but I find it odd that Params,
Returns, and maybe others are accepted for modules, aliases, classes, and
probably other elements. I mean, what does a module return? What are the
parameters of an alias? I think ddoc shouldn't allow those sections, but I'm not
sure what the exact behavior should be.

And as a related note, whatever is done with the previous issue, should also be done when trying to document parameters that don't exist:

/// Params:
/// a = nothing
void foo() {}

-- 
Carlos Santander Bernal

Carlos Santander wrote:
> I'm not sure if this should be flagged as a bug, but I find it odd that Params,
> Returns, and maybe others are accepted for modules, aliases, classes, and
> probably other elements. I mean, what does a module return? What are the
> parameters of an alias? I think ddoc shouldn't allow those sections, but I'm not sure what the exact behavior should be.
<snip>

If it's a template declared using the

    class C(T)

notation, then it's the template parameter.  For an alias of a function pointer or delegate type, it's the parameters of the function to be expected.

Speaking of which, does any documentation system support a good way of documenting the parameters/returns of function pointers/delegates that are themselves parameter or return types?

Stewart.

-- 
-----BEGIN GEEK CODE BLOCK-----
Version: 3.1
GCS/M d- s:-@ C++@ a->--- UB@ P+ L E@ W++@ N+++ o K-@ w++@ O? M V? PS- PE- Y? PGP- t- 5? X? R b DI? D G e++++ h-- r-- !y
------END GEEK CODE BLOCK------

My e-mail is valid but not my primary mailbox.  Please keep replies on the 'group where everyone may benefit.

Stewart Gordon escribió:
> Carlos Santander wrote:
>> I'm not sure if this should be flagged as a bug, but I find it odd that Params,
>> Returns, and maybe others are accepted for modules, aliases, classes, and
>> probably other elements. I mean, what does a module return? What are the
>> parameters of an alias? I think ddoc shouldn't allow those sections, but I'm not sure what the exact behavior should be.
> <snip>
> 
> If it's a template declared using the
> 
>     class C(T)
> 

Then it's a template and not a class. I never mentioned templates.

> notation, then it's the template parameter.  For an alias of a function pointer or delegate type, it's the parameters of the function to be expected.

Well, that's an special case, the exception to the rule ;)

> 
> Speaking of which, does any documentation system support a good way of documenting the parameters/returns of function pointers/delegates that are themselves parameter or return types?

I have no idea, but I can't imagine how that would work.

> 
> Stewart.
> 


-- 
Carlos Santander Bernal

Carlos Santander wrote:
> I'm not sure if this should be flagged as a bug, but I find it odd that Params,
> Returns, and maybe others are accepted for modules, aliases, classes, and
> probably other elements. I mean, what does a module return? What are the
> parameters of an alias? I think ddoc shouldn't allow those sections, but I'm not
> sure what the exact behavior should be.
> 
> And as a related note, whatever is done with the previous issue, should also be done when trying to document parameters that don't exist:
> 
> /// Params:
> /// a = nothing
> void foo() {}

Sometimes there are parameters to functions that aren't in the function's parameter list, such as a global variable.

One of the design goals for Ddoc is that it doesn't produce error messages - it attempts to produce reasonable output regardless.

Walter Bright escribió:
> Carlos Santander wrote:
>> I'm not sure if this should be flagged as a bug, but I find it odd that Params,
>> Returns, and maybe others are accepted for modules, aliases, classes, and
>> probably other elements. I mean, what does a module return? What are the
>> parameters of an alias? I think ddoc shouldn't allow those sections, but I'm not
>> sure what the exact behavior should be.
>>
>> And as a related note, whatever is done with the previous issue, should also be done when trying to document parameters that don't exist:
>>
>> /// Params:
>> /// a = nothing
>> void foo() {}
> 
> Sometimes there are parameters to functions that aren't in the function's parameter list, such as a global variable.
> 
> One of the design goals for Ddoc is that it doesn't produce error messages - it attempts to produce reasonable output regardless.

I guess that kinda makes sense, even if I don't understand what a class might return... he he... I don't know, I supposed some things could be marked as invalid in some places, but that goes against Ddoc design. Oh well, it's good to  know, anyway.

-- 
Carlos Santander Bernal