www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.bugs - ddoc: Params for all elements?

reply 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
May 14 2006
next sibling parent reply 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.

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.
May 15 2006
parent 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.

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
May 15 2006
prev sibling parent reply 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.
May 22 2006
parent 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
May 23 2006