I had an enhancement idea for ddoc.  I figured I throw it out there.  I actually had this concept just before I read the ddoc announcement.

I have never been good about keeping comment blocks in sync with the code.  (I'm just a hobbyist, so no body is paying me to do a bad job.) So, my idea basically ties the comments in with the code to (IMO) make the job of documenting easier.

For function/method declarations, the parameter documentation would go in the parameter list.  The inline comments could be appended to the 'Params' section.  A good idea would also be to have a default location for the params section.  So, the example from the ddoc documentation would be equivalently written:

	/***********************************
	 * foo does this.
	 */
	void foo(int x, /++ is for this and not for that +/
		 int y  /++ is for that +/ )
	{
	}


Also, returns and throws would be inlined.  Each documented return or throw statement could/would be bullet listed, with explanations of how you got there.  For returns of constant values (true, false, enumerations), this would give explanations of how each exit point is reached, with the corresponding value.  Returning variables would only line the document string.

	return BLUE; /// held breath too long

The documentation would include "BLUE" and the string "held breath too long".  And, likewise, exceptions would give the exception type thrown.

	return result; /// array of slices into string[]

This would only "export" array of slices into string[].



The advantages I see to this approach are:
- Documentation is closer to the code, and automatically updated if the code changes.  For example, changing a parameter name changes the documentation automatically, instead of having to change the parameter name in 2 locations.
- Exception types and return info would track automatically.  When adding or removing throws and returns, the list grows and shrinks accordingly.
- You can generate warnings about missing documentation.  If you forget to document an return statement, then ddoc would warn you that function foo had N undocumented return statements... or N undocumented throw statements.
- This could coexist with the current code base.

The disadvantage:
- I'm not the guy you want implementing it.


Kurt Anderson

I like this idea. However I think the syntax needs to be deeper if it's going to be useable, otherwise there's a danger of just making the code messy. What I mean by "deeper" is making the comments for parameters etc. part of the language syntax, rather than ordinary comments. The problem with that of course is that we really don't want to be changing fundamental stuff like that at this stage!

Here's a (v. poor) syntax example off the top of my head:

     /***********************************
      * foo does this.
      */
     void foo(int x :is for this and not for that,
              int y :is for that )
     {
     }

But also, I think it's useful to be able to mark out sections of a source code file as applicable to particular concept. E.g. it might be nice if you could mark out an "Accessors" section and a "Modifiers" section in your class definitions, so that the doc for the class can arrange itself into subsections. I'm not suggesting hard coding of section names, but that you could add them as you wish. This sort of facility is available in Doxygen, but the syntax is horrible because it's add-on syntax using special comments, rather than being part of the language. It would be nice if we could have a section keyword eg.

    section Accessors : These methods get information about
                        an object of this class, but do not
                        modify it.
    {
        etc.
    }

Like I say, this is probably too much of a change right now though!

Cheers

Raffles


Kurt Anderson wrote:
> 
> I had an enhancement idea for ddoc.  I figured I throw it out there.  I actually had this concept just before I read the ddoc announcement.
> 
> I have never been good about keeping comment blocks in sync with the code.  (I'm just a hobbyist, so no body is paying me to do a bad job.) So, my idea basically ties the comments in with the code to (IMO) make the job of documenting easier.
> 
> For function/method declarations, the parameter documentation would go in the parameter list.  The inline comments could be appended to the 'Params' section.  A good idea would also be to have a default location for the params section.  So, the example from the ddoc documentation would be equivalently written:
> 
>     /***********************************
>      * foo does this.
>      */
>     void foo(int x, /++ is for this and not for that +/
>          int y  /++ is for that +/ )
>     {
>     }
> 
> 
> Also, returns and throws would be inlined.  Each documented return or throw statement could/would be bullet listed, with explanations of how you got there.  For returns of constant values (true, false, enumerations), this would give explanations of how each exit point is reached, with the corresponding value.  Returning variables would only line the document string.
> 
>     return BLUE; /// held breath too long
> 
> The documentation would include "BLUE" and the string "held breath too long".  And, likewise, exceptions would give the exception type thrown.
> 
>     return result; /// array of slices into string[]
> 
> This would only "export" array of slices into string[].
> 
> 
> 
> The advantages I see to this approach are:
> - Documentation is closer to the code, and automatically updated if the code changes.  For example, changing a parameter name changes the documentation automatically, instead of having to change the parameter name in 2 locations.
> - Exception types and return info would track automatically.  When adding or removing throws and returns, the list grows and shrinks accordingly.
> - You can generate warnings about missing documentation.  If you forget to document an return statement, then ddoc would warn you that function foo had N undocumented return statements... or N undocumented throw statements.
> - This could coexist with the current code base.
> 
> The disadvantage:
> - I'm not the guy you want implementing it.
> 
> 
> Kurt Anderson
> 

Raffles munchgreeble xxATxx bigfoot xxDOTxx com wrote:
> But also, I think it's useful to be able to mark out sections of a source code file as applicable to particular concept. E.g. it might be nice if you could mark out an "Accessors" section and a "Modifiers" section in your class definitions, so that the doc for the class can arrange itself into subsections. I'm not suggesting hard coding of section names, but that you could add them as you wish. This sort of facility is available in Doxygen, but the syntax is horrible because it's add-on syntax using special comments, rather than being part of the language. It would be nice if we could have a section keyword eg.
> 
>     section Accessors : These methods get information about
>                         an object of this class, but do not
>                         modify it.
>     {
>         etc.
>     }
> 

I do like this concept.  Maybe the DDoc way would be something like:

# /++
#  + Foo is a class for doing blah blah blah.
#  +/
# class Foo {
# /// section: Accessors {
#   /++
#    + do the this and such
#    +/
#   int bar () {
#     // ...
#   }
# /// }
#
# /// section: Modifiers {
# /// }
# }

-- Chris Sauls

Raffles munchgreeble xxATxx bigfoot xxDOTxx com wrote:
> I like this idea. However I think the syntax needs to be deeper if it's going to be useable, otherwise there's a danger of just making the code messy. What I mean by "deeper" is making the comments for parameters etc. part of the language syntax, rather than ordinary comments. The problem with that of course is that we really don't want to be changing fundamental stuff like that at this stage!

I, too, would have liked something as a part of the language.  The best I could picture was a "doc()" directive, like "version()".  Walter, however, beat me out by getting ddoc out there.  Oh well.

I do fear the "messy" factor.  I looked at a CWEB snippet quickly.  I couldn't find the C code.  I realize the goal is different, but I just thought it was too much.


Kurt Anderson