• Carlos Santander (12/12) May 14 2006 I'm not sure if this should be flagged as a bug, but I find it odd that ...
• Stewart Gordon (19/25) May 15 2006
• Carlos Santander (6/29) May 15 2006 Well, that's an special case, the exception to the rule ;)
• Walter Bright (5/19) May 22 2006 Sometimes there are parameters to functions that aren't in the
• Carlos Santander (7/28) May 23 2006 I guess that kinda makes sense, even if I don't understand what a class ...

Carlos Santander <csantander619 gmail.com> writes:

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

Stewart Gordon <smjg_1998 yahoo.com> writes:

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.

Carlos Santander <csantander619 gmail.com> writes:

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

Walter Bright <newshound digitalmars.com> writes:

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.

Carlos Santander <csantander619 gmail.com> writes:

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