View mode: basic / threaded / horizontal-split · Log in · Help
December 10, 2005
"inline" commenting - ddoc idea
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
December 20, 2005
Re: "inline" commenting - ddoc idea
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
>
December 20, 2005
Re: "inline" commenting - ddoc idea
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
December 22, 2005
Re: "inline" commenting - ddoc idea
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
Top | Discussion index | About this forum | D home