www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - "inline" commenting - ddoc idea

reply Kurt Anderson <kurtanderson fastmail.fm> writes:
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
Dec 10 2005
parent reply Raffles munchgreeble xxATxx bigfoot xxDOTxx com <"a" b.com> writes:
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
Dec 20 2005
next sibling parent Chris Sauls <ibisbasenji gmail.com> writes:
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:


















-- Chris Sauls
Dec 20 2005
prev sibling parent Kurt Anderson <kurtanderson fastmail.fm> writes:
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
Dec 22 2005