www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.announce - Embedded Documentation in Comments

reply "Walter" <newshound digitalmars.com> writes:
I've put up a strawman proposal for embedding documentation in comments at
www.digitalmars.com/d/doc.html
Aug 27 2005
next sibling parent reply Vathix <chris dprogramming.com> writes:
On Sat, 27 Aug 2005 04:47:18 -0400, Walter <newshound digitalmars.com>  
wrote:


 I've put up a strawman proposal for embedding documentation in comments  
 at
 www.digitalmars.com/d/doc.html


Page not found.
Aug 27 2005
parent "Walter" <newshound digitalmars.com> writes:
"Vathix" <chris dprogramming.com> wrote in message
news:op.sv5s10p1l2lsvj esi...

 On Sat, 27 Aug 2005 04:47:18 -0400, Walter <newshound digitalmars.com>
 wrote:


 I've put up a strawman proposal for embedding documentation in comments
 at
 www.digitalmars.com/d/doc.html


 Page not found.


Oops. It's there now.
Aug 27 2005
prev sibling next sibling parent reply Vathix <chris dprogramming.com> writes:
On Sat, 27 Aug 2005 04:47:18 -0400, Walter <newshound digitalmars.com>  
wrote:


 I've put up a strawman proposal for embedding documentation in comments  
 at
 www.digitalmars.com/d/doc.html


Not bad. What I don't seem to like is the "Params:" alternate method of  
documenting a function's parameters. I don't like the idea of lining  
things up in order for it to be parsed correctly. It leads to tabs/spaces  
conflicts. How about prefixing the identifier with   and it will continue  
until another  identifier or the end of the comment. People will still  
probably line them up, but using tabs and spaces however they please.

A suggestion I have is a way to document if a function should be used as a  
property and not a function. Perhaps "Property: get" / "Property: set",  
that way a documentation generator could group them and strip the () from  
the display to further discourage them from being used as functions.
Aug 27 2005
next sibling parent reply "Ben Hinkle" <ben.hinkle gmail.com> writes:
"Vathix" <chris dprogramming.com> wrote in message 
news:op.sv5uwjdol2lsvj esi...

 On Sat, 27 Aug 2005 04:47:18 -0400, Walter <newshound digitalmars.com> 
 wrote:


 I've put up a strawman proposal for embedding documentation in comments 
 at
 www.digitalmars.com/d/doc.html


 Not bad. What I don't seem to like is the "Params:" alternate method of 
 documenting a function's parameters. I don't like the idea of lining 
 things up in order for it to be parsed correctly. It leads to tabs/spaces 
 conflicts. How about prefixing the identifier with   and it will continue 
 until another  identifier or the end of the comment. People will still 
 probably line them up, but using tabs and spaces however they please.


It's true that spacing is an issue but   symbols are ugly and I'm glad 
Walter is avoiding them. How about "more leading whitespace than the 
previous line" means a continued param doc.


 A suggestion I have is a way to document if a function should be used as a 
 property and not a function. Perhaps "Property: get" / "Property: set", 
 that way a documentation generator could group them and strip the () from 
 the display to further discourage them from being used as functions.


I agree properties should be special. Your idea of property get/set seems 
fine to me.
Aug 27 2005
parent reply Vathix <chris dprogramming.com> writes:
On Sat, 27 Aug 2005 08:13:28 -0400, Ben Hinkle <ben.hinkle gmail.com>  
wrote:


 "Vathix" <chris dprogramming.com> wrote in message
 news:op.sv5uwjdol2lsvj esi...

 On Sat, 27 Aug 2005 04:47:18 -0400, Walter <newshound digitalmars.com>
 wrote:


 I've put up a strawman proposal for embedding documentation in comments
 at
 www.digitalmars.com/d/doc.html


 Not bad. What I don't seem to like is the "Params:" alternate method of
 documenting a function's parameters. I don't like the idea of lining
 things up in order for it to be parsed correctly. It leads to  
 tabs/spaces
 conflicts. How about prefixing the identifier with   and it will  
 continue
 until another  identifier or the end of the comment. People will still
 probably line them up, but using tabs and spaces however they please.


 It's true that spacing is an issue but   symbols are ugly and I'm glad
 Walter is avoiding them. How about "more leading whitespace than the
 previous line" means a continued param doc.


All right, but that suggests you have to keep on adding more and more  
whitespace for more lines, like

/** This is my function.
  * Params:
  *     fp    File pointer
  *     name  File name and
  *           more. Some more
  *            can go here but
  *             you have to add
  *              more and more
  *               spaces.
  */

"more leading whitespace than the line containing the identifier" or  
similar seems better.
Aug 27 2005
next sibling parent "Ben Hinkle" <ben.hinkle gmail.com> writes:
"Vathix" <chris dprogramming.com> wrote in message 
news:op.sv53g81jl2lsvj esi...

 On Sat, 27 Aug 2005 08:13:28 -0400, Ben Hinkle <ben.hinkle gmail.com> 
 wrote:


 "Vathix" <chris dprogramming.com> wrote in message
 news:op.sv5uwjdol2lsvj esi...

 On Sat, 27 Aug 2005 04:47:18 -0400, Walter <newshound digitalmars.com>
 wrote:


 I've put up a strawman proposal for embedding documentation in comments
 at
 www.digitalmars.com/d/doc.html


 Not bad. What I don't seem to like is the "Params:" alternate method of
 documenting a function's parameters. I don't like the idea of lining
 things up in order for it to be parsed correctly. It leads to 
 tabs/spaces
 conflicts. How about prefixing the identifier with   and it will 
 continue
 until another  identifier or the end of the comment. People will still
 probably line them up, but using tabs and spaces however they please.


 It's true that spacing is an issue but   symbols are ugly and I'm glad
 Walter is avoiding them. How about "more leading whitespace than the
 previous line" means a continued param doc.


 All right, but that suggests you have to keep on adding more and more 
 whitespace for more lines, like

 /** This is my function.
  * Params:
  *     fp    File pointer
  *     name  File name and
  *           more. Some more
  *            can go here but
  *             you have to add
  *              more and more
  *               spaces.
  */

 "more leading whitespace than the line containing the identifier" or 
 similar seems better.


whoops - good point :-)
Aug 27 2005
prev sibling parent Jason Mills <jmills cs.mun.ca> writes:
Vathix wrote:

 On Sat, 27 Aug 2005 08:13:28 -0400, Ben Hinkle <ben.hinkle gmail.com>  
 wrote:

 It's true that spacing is an issue but   symbols are ugly and I'm glad
 Walter is avoiding them. How about "more leading whitespace than the
 previous line" means a continued param doc.


 
 
 All right, but that suggests you have to keep on adding more and more  
 whitespace for more lines, like
 
 /** This is my function.
  * Params:
  *     fp    File pointer
  *     name  File name and
  *           more. Some more
  *            can go here but
  *             you have to add
  *              more and more
  *               spaces.
  */
 
 "more leading whitespace than the line containing the identifier" or  
 similar seems better.



Why not simply use : or - after each parameter. I haven't thought about 
this too much, but this seems natural, looks good, and avoids ugly 
prefixes and the requirement for lining parameters up exactly. For example,

/** This is my function.
  * Params:
  *     fp:   File pointer
  *     name: File name
  */

or

/** This is my function.
  * Params:
  *     fp - File pointer
  *     name - File name
  */

Alternatively, you could view more then one parameter as a list of 
definitions, where list items are identified by the prefix - and the 
defined term is identified by the ending :. For example,

/** This is my function.
  * Params:
  *     - fp: File pointer
  *     - name: File name
  */

I suppose you wouldn't need the : after the parameter name since names 
don't contain spaces.

Jason
Aug 27 2005
prev sibling parent "Walter" <newshound digitalmars.com> writes:
"Vathix" <chris dprogramming.com> wrote in message
news:op.sv5uwjdol2lsvj esi...

 Not bad. What I don't seem to like is the "Params:" alternate method of
 documenting a function's parameters. I don't like the idea of lining
 things up in order for it to be parsed correctly. It leads to tabs/spaces
 conflicts. How about prefixing the identifier with   and it will continue
 until another  identifier or the end of the comment. People will still
 probably line them up, but using tabs and spaces however they please.


I see your point, but I don't like the   business because it doesn't look
like something someone would naturally write. An alternative that might work
is looking for:
    name=value
syntax.


 A suggestion I have is a way to document if a function should be used as a
 property and not a function. Perhaps "Property: get" / "Property: set",
 that way a documentation generator could group them and strip the () from
 the display to further discourage them from being used as functions.
Aug 27 2005
prev sibling next sibling parent reply "Ben Hinkle" <ben.hinkle gmail.com> writes:
"Walter" <newshound digitalmars.com> wrote in message 
news:depaee$fre$1 digitaldaemon.com...

 I've put up a strawman proposal for embedding documentation in comments at
 www.digitalmars.com/d/doc.html


Nice. Some thoughts:
- how about also having a License: section or something for any legal stuff 
that users need to know about.
- allowing a wiki markup instead of embedded html solves the problem of just 
how much html is supported by a given tool. I'm just thinking of italics, 
bold, bold-italics, list and numbered lists and maybe a few others that I 
can't think of now. like monospaced-fonts or code.
- should the Code block be Example? I'm not sure what kind of code to put in 
Code.
Aug 27 2005
parent "Walter" <newshound digitalmars.com> writes:
"Ben Hinkle" <ben.hinkle gmail.com> wrote in message
news:depkh8$n10$1 digitaldaemon.com...

 "Walter" <newshound digitalmars.com> wrote in message
 news:depaee$fre$1 digitaldaemon.com...

 I've put up a strawman proposal for embedding documentation in comments




at

 www.digitalmars.com/d/doc.html


 Nice. Some thoughts:
 - how about also having a License: section or something for any legal


stuff

 that users need to know about.


That's a good idea.


 - allowing a wiki markup instead of embedded html solves the problem of


just

 how much html is supported by a given tool. I'm just thinking of italics,
 bold, bold-italics, list and numbered lists and maybe a few others that I
 can't think of now. like monospaced-fonts or code.


There's always someone who's going to want to use the full capability of
html. It's also easier to support in the documentation extractor - any html
is just echo'd to the output.


 - should the Code block be Example? I'm not sure what kind of code to put


in

 Code.


It would be D code going in code blocks. I thought of calling it example:,
but examples often contain much more than just code.
Aug 27 2005
prev sibling next sibling parent reply J Thomas <jtd514 ameritech.net> writes:
Excelent ideas. Are you planning on having the compiler produce the 
documentation itself? That would be killer!


Walter wrote:

 I've put up a strawman proposal for embedding documentation in comments at
 www.digitalmars.com/d/doc.html
Aug 27 2005
next sibling parent "Charles" <noone nowhere.com> writes:
 That would be killer!


Yea it would.


"J Thomas" <jtd514 ameritech.net> wrote in message
news:depov4$pqd$1 digitaldaemon.com...

 Excelent ideas. Are you planning on having the compiler produce the
 documentation itself? That would be killer!


 Walter wrote:

 I've put up a strawman proposal for embedding documentation in comments




at

 www.digitalmars.com/d/doc.html
Aug 27 2005
prev sibling parent "Walter" <newshound digitalmars.com> writes:
"J Thomas" <jtd514 ameritech.net> wrote in message
news:depov4$pqd$1 digitaldaemon.com...

 Excelent ideas. Are you planning on having the compiler produce the
 documentation itself? That would be killer!


Yes, since the power of a default documentation system that is installed on
every D user's machine is overwhelming. It'll produce a strong incentive to
use it, thereby homogenizing the look/feel of documentation. It's the same
reason why debug is in the language rather than a convention.

The ubiquity of javadoc for java code is a case in point - contrasted with
the various incompatible competing schemes for C++.
Aug 27 2005
prev sibling next sibling parent reply Hasan Aljudy <hasan.aljudy gmail.com> writes:
Walter wrote:

 I've put up a strawman proposal for embedding documentation in comments at
 www.digitalmars.com/d/doc.html
 
 


Nice ideas, and the code/doc looks pretty clean too.

One objection: the first form of param documentation looks ugly (to me):
void foo(
	int x,  // is for this
	int y   // is for that
	)


And for the 'Deprecated', it seems redundant, the compiler already knows 
the function is deprecated.
I think the only thing to document about a deprecated function is why 
it's deprecated, and what should we use instead of it.

/**
     Use bar() instead
*/
deprecated void foo() { ... }

Embedded HTML doesn't look very good :/
Aug 27 2005
parent "Walter" <newshound digitalmars.com> writes:
"Hasan Aljudy" <hasan.aljudy gmail.com> wrote in message
news:deprnl$vqb$1 digitaldaemon.com...

 One objection: the first form of param documentation looks ugly (to me):
 void foo(
 int x,  // is for this
 int y   // is for that
 )


Yes, that doesn't look too hot even though it is more "pure", which is why I
reluctantly decided to add the Params: section.



 And for the 'Deprecated', it seems redundant, the compiler already knows
 the function is deprecated.


Right, but there isn't an obvious way to automatically associate an
explanation with it. For example, a more user friendly compiler could issue
along with a deprecation error message the contents of the Deprecated:
section.


 /**
      Use bar() instead
 */
 deprecated void foo() { ... }

 Embedded HTML doesn't look very good :/


I know, that's why for conventional documentation it won't be necessary.
It's only there for people who absolutely need to do something extra and for
me to avoid having to add endless features to the documentation extractor.
Aug 27 2005
prev sibling next sibling parent "Ameer Armaly" <ameer_armaly hotmail.com> writes:
"Walter" <newshound digitalmars.com> wrote in message 
news:depaee$fre$1 digitaldaemon.com...

 I've put up a strawman proposal for embedding documentation in comments at
 www.digitalmars.com/d/doc.html


Looks good, especially since this type of info helps people understand the 
code while they're reading it, and then poof you have  a ready to go manual.
Aug 27 2005
prev sibling next sibling parent reply Bruno Medeiros <daiphoenixNO SPAMlycos.com> writes:
Walter wrote:

 I've put up a strawman proposal for embedding documentation in comments at
 www.digitalmars.com/d/doc.html
 


Speaking of which, and considering what Walter said on the other thread( 

needlessly and excessively klunky." ), what is the problem with Javadoc? 

ok to me (and is mostly similiar to that proposal). Is it because just 
the   symbol? (Ben Hinkle commented elsewhere on this thread that it was 
ugly) wth.. what's so ugly about the AT symbol? :o

-- 
Bruno Medeiros
Computer Science/Engineering student
Aug 27 2005
next sibling parent reply "Ben Hinkle" <ben.hinkle gmail.com> writes:
[snip]

 (and is mostly similiar to that proposal). Is it because just the   
 symbol? (Ben Hinkle commented elsewhere on this thread that it was ugly) 
 wth.. what's so ugly about the AT symbol? :o


 because  human-readable  text  doesn't  have  ats  in  it
Aug 27 2005
next sibling parent reply James Dunne <james.jdunne gmail.com> writes:
In article <deq7p5$1o63$1 digitaldaemon.com>, Ben Hinkle says...

[snip]

 (and is mostly similiar to that proposal). Is it because just the   
 symbol? (Ben Hinkle commented elsewhere on this thread that it was ugly) 
 wth.. what's so ugly about the AT symbol? :o


 because  human-readable  text  doesn't  have  ats  in  it


It was mentioned that identifiers would automatically be emphasized.  I'm
wondering if that would get annoying if you had a class member named 'a' or some
other common english term that you'd use in your docs...  I think a special
marker character should be used to deliniate identifiers from regular
documentation.  It doesn't have to be  .  How about placing parens or curlies
around it?

/**
* Remarks:  When using (myMember), don't forget to check for null!
*/

Regards,
James Dunne
Aug 27 2005
parent "Walter" <newshound digitalmars.com> writes:
"James Dunne" <james.jdunne gmail.com> wrote in message
news:deq9tp$1pjj$1 digitaldaemon.com...

 It was mentioned that identifiers would automatically be emphasized.  I'm
 wondering if that would get annoying if you had a class member named 'a'


or some

 other common english term that you'd use in your docs...  I think a


special

 marker character should be used to deliniate identifiers from regular
 documentation.  It doesn't have to be  .  How about placing parens or


curlies

 around it?


That could be a problem, and it probably *would* discourage giving
parameters names like 'a'. This might not be a bad thing. But in the doc it
does mention that prefixing a name with a '_' would disable emphasizing it,
and the '_' would be stripped.
Aug 27 2005
prev sibling next sibling parent Dave <Dave_member pathlink.com> writes:
In article <deq7p5$1o63$1 digitaldaemon.com>, Ben Hinkle says...

[snip]

 (and is mostly similiar to that proposal). Is it because just the   
 symbol? (Ben Hinkle commented elsewhere on this thread that it was ugly) 
 wth.. what's so ugly about the AT symbol? :o


 because  human-readable  text  doesn't  have  ats  in  it


What? Could you repeat that <g>
Aug 27 2005
prev sibling next sibling parent reply Bruno Medeiros <daiphoenixNO SPAMlycos.com> writes:
Ben Hinkle wrote:

 [snip]
 

(and is mostly similiar to that proposal). Is it because just the   
symbol? (Ben Hinkle commented elsewhere on this thread that it was ugly) 
wth.. what's so ugly about the AT symbol? :o


 
 
  because  human-readable  text  doesn't  have  ats  in  it
 


...Huh? What: you: said: does: not: make: sense: at: all:

Certainly you don't think we are to put marker symbols (whatever they 
be) in every word of the comment documentation, which is what you 
implied. Please restate.


-- 
Bruno Medeiros
Computer Science/Engineering student
Aug 27 2005
parent reply "Ben Hinkle" <ben.hinkle gmail.com> writes:
"Bruno Medeiros" <daiphoenixNO SPAMlycos.com> wrote in message 
news:deqd0j$1rq5$1 digitaldaemon.com...

 Ben Hinkle wrote:

 [snip]


(and is mostly similiar to that proposal). Is it because just the   
symbol? (Ben Hinkle commented elsewhere on this thread that it was ugly) 
wth.. what's so ugly about the AT symbol? :o



  because  human-readable  text  doesn't  have  ats  in  it


 ...Huh? What: you: said: does: not: make: sense: at: all:

 Certainly you don't think we are to put marker symbols (whatever they be) 
 in every word of the comment documentation, which is what you implied. 
 Please restate.


I was using "dramatic license" to make my point. For a more serious answer 
look around you in the real world at forms containing information like 
application forms  or bills and you'll see stuff like

  address: 7 blah blah St
  phone: 123-456-7890
  account number: 1

Using : is a standard clue to humans. Using   is great for computers but 
isn't natural for humans.
Aug 27 2005
next sibling parent reply Mike Parker <aldacron71 yahoo.com> writes:
Ben Hinkle wrote:


 
 Using : is a standard clue to humans. Using   is great for computers but 
 isn't natural for humans.
 
 


But on the other hand, once you've worked with Java for a while the   
symbols don't bother you at all. In fact, they stand out when perusing 
the source and pull your eyes to the important parts of the 
documentation. Not that I'm saying we should have them in D, but they 
really aren't all bad.
Aug 27 2005
next sibling parent reply jmjmak utu.invalid.fi writes:
In article <deqfvm$1upi$1 digitaldaemon.com>, Mike Parker says...

Ben Hinkle wrote:


 
 Using : is a standard clue to humans. Using   is great for computers but 
 isn't natural for humans.
 
 


But on the other hand, once you've worked with Java for a while the   
symbols don't bother you at all. In fact, they stand out when perusing 
the source and pull your eyes to the important parts of the 
documentation. Not that I'm saying we should have them in D, but they 
really aren't all bad.


Speaking of javadoc, I hope we're not reinventing the wheel here. Both javadoc
and doxygen use a well known documentation syntax. Doxygen even supports d (not
completely though) already. I really hope a working doxygen support is
everything we ever need.
Aug 27 2005
parent "Walter" <newshound digitalmars.com> writes:
<jmjmak utu.invalid.fi> wrote in message
news:deqirp$21vn$1 digitaldaemon.com...

 Speaking of javadoc, I hope we're not reinventing the wheel here. Both


javadoc

 and doxygen use a well known documentation syntax. Doxygen even supports d


(not

 completely though) already. I really hope a working doxygen support is
 everything we ever need.


This scheme will not impede anyone's use of Doxygen or a javadoc clone.

javadoc is pretty good, though it has some disadvantages:

1) Unnecessary overreliance on HTML. You need to use <p>, <code> ... </code>
tags, etc., for basic use. I don't think <p> is necessary to separate
paragraphs - why not a blank line? This will make it difficult to target
something other than HTML with the documentation extractor.

2) Unnecessary use of  . Already discussed elsewhere.
Aug 27 2005
prev sibling parent reply "Ben Hinkle" <ben.hinkle gmail.com> writes:
"Mike Parker" <aldacron71 yahoo.com> wrote in message 
news:deqfvm$1upi$1 digitaldaemon.com...

 Ben Hinkle wrote:


 Using : is a standard clue to humans. Using   is great for computers but 
 isn't natural for humans.


 But on the other hand, once you've worked with Java for a while the   
 symbols don't bother you at all. In fact, they stand out when perusing the 
 source and pull your eyes to the important parts of the documentation. Not 
 that I'm saying we should have them in D, but they really aren't all bad.


heh - I've never really liked how Javadoc looks. :-)
Even all the  params and  return bug me since most of the time the meaning 
is obvious, especially with Java's recommendation for long descriptive 
names. For example

 /** Adds two integers and wraps on overflow.
  *  param x the first integer to add
  *  param y the second integer to add
  *  return the sum of x and y
  */
 int add(int x, int y)

like, duh.
Aug 27 2005
parent "Walter" <newshound digitalmars.com> writes:
"Ben Hinkle" <ben.hinkle gmail.com> wrote in message
news:deqmu5$25jg$1 digitaldaemon.com...

 heh - I've never really liked how Javadoc looks. :-)
 Even all the  params and  return bug me since most of the time the meaning
 is obvious, especially with Java's recommendation for long descriptive
 names. For example

  /** Adds two integers and wraps on overflow.
   *  param x the first integer to add
   *  param y the second integer to add
   *  return the sum of x and y
   */
  int add(int x, int y)

 like, duh.


I think I'll have Ddoc issue a fatal error message if any attempt is made to
'document' a return value of void. <g>
Aug 27 2005
prev sibling next sibling parent reply "Walter" <newshound digitalmars.com> writes:
"Ben Hinkle" <ben.hinkle gmail.com> wrote in message
news:deqf9e$1ugt$1 digitaldaemon.com...

 I was using "dramatic license" to make my point. For a more serious answer
 look around you in the real world at forms containing information like
 application forms  or bills and you'll see stuff like

   address: 7 blah blah St
   phone: 123-456-7890
   account number: 1

 Using : is a standard clue to humans. Using   is great for computers but
 isn't natural for humans.


Using a postfix : isn't any harder for computers, so the argument for   just
falls away.
Aug 27 2005
parent Bruno Medeiros <daiphoenixNO SPAMlycos.com> writes:
Walter wrote:

 
 Using a postfix : isn't any harder for computers, so the argument for   just
 falls away.
 


What argument about being easier or harder for computers? No one was 
saying that. (it makes no difference for them computers, obviously)

-- 
Bruno Medeiros
Computer Science/Engineering student
Aug 27 2005
prev sibling parent reply Bruno Medeiros <daiphoenixNO SPAMlycos.com> writes:
Ben Hinkle wrote:

 
 I was using "dramatic license" to make my point. For a more serious answer 
 look around you in the real world at forms containing information like 
 application forms  or bills and you'll see stuff like
 
   address: 7 blah blah St
   phone: 123-456-7890
   account number: 1
 
 Using : is a standard clue to humans. Using   is great for computers but 
 isn't natural for humans.
 


The following seems to me much more natural(better word: readable) :

/**
  * Returns an Image object that can then be painted on the screen.
  * The url argument must specify an absolute { link URL}. The name
  * argument is a specifier that is relative to the url argument.
  *
  *  param  url  an absolute URL giving the base location of the image
  *  param  name the location of the image, relative to the url argument
  *  return      the image at the specified URL
  *  see         Image
  */

than the equivalent in D proposal:

/**
  * Returns an Image object that can then be painted on the screen.
  * The url argument must specify an absolute { link URL}. The name
  * argument is a specifier that is relative to the url argument.
  *
  * Params:
  * 	url   an absolute URL giving the base location of the image
  * 	name  the location of the image, relative to the url argument
  * return:    the image at the specified URL
  * see:       Image
  */

The " " stands out much better. Explained in longer words:

I was going to say that we, as coders, are quite capable of dealing with 
that. But actually I think that any non-coder human would just as easily 
understand " " as ":" , if explained the meaning. We humans are 
inefficient at processing obfuscated or large amounts of information. 
" " is neither larger or more obfuscated than ":".
You may prefer ":" because in human language it already has a meaning 
similiar to what we want as a code keyword (or keysymbol), and thus you 
say it is more natural. But it doesn't we mean we wouldn't adapt easily 
(or in fact *instantly*) to a different symbol.

Indeed, while before I didn't think it made a difference (I was just 
considering compatibility with existing standards), now that you made me 
think about it, I do prefer " " for the exact same reason you mentioned: 
that ":" already has a meaning in human language! And so one uses " " 
for meta-language purposes because that's what the symbol will do 
(specifying "sections" as Walter called it), and ":" for proper 
human-language. Otherwise if one uses ":" as a keysymbol, one cannot use 
it in the human-language part (i.e. item description) or at least will 
have limitations, and/or confusion when using it.

-- 
Bruno Medeiros
Computer Science/Engineering student
Aug 27 2005
next sibling parent reply "Walter" <newshound digitalmars.com> writes:
"Bruno Medeiros" <daiphoenixNO SPAMlycos.com> wrote in message
news:deqm53$252u$1 digitaldaemon.com...

 The following seems to me much more natural(better word: readable) :

 /**
   * Returns an Image object that can then be painted on the screen.
   * The url argument must specify an absolute { link URL}. The name
   * argument is a specifier that is relative to the url argument.
   *
   *  param  url  an absolute URL giving the base location of the image
   *  param  name the location of the image, relative to the url argument
   *  return      the image at the specified URL
   *  see         Image
   */

 than the equivalent in D proposal:


I'd write it as this (with the caveat that it won't look quite right using a
proportional font):

/**
  * Returns an Image object that can then be painted on the screen.
  *
  * The url argument must specify an absolute URL. The name
  * argument is a specifier that is relative to the url argument.
  *
  * Params:
  *     url        an absolute URL giving the base location of the image
  *     name    the location of the image, relative to the url argument
  *
  * Returns:
  *                 the image at the specified URL
  * See:
  *                Image
  */

It already looks like a typical manual page. I've never seen a manual page
that used  's for emphasis (or any book printed since Gutenberg, for that
matter).



 And so one uses " "
 for meta-language purposes because that's what the symbol will do
 (specifying "sections" as Walter called it), and ":" for proper
 human-language.


A big goal for Ddoc (for lack of a better term!) is to have it look right in
a proper human-language. I don't want it to look like computer code.



 Otherwise if one uses ":" as a keysymbol, one cannot use
 it in the human-language part (i.e. item description) or at least will
 have limitations, and/or confusion when using it.


Yes, that can be an issue, but I think it is very minimal. Section keywords
must be the first non-whitespace on a line, and they must be immediately
followed by the ':'. This means that a ':' in any other context is not
significant. So, several workarounds are possible if this should occur
(which I feel is unlikely):

1) put a space between the name and the ':'
2) put &nbsp; in front of the name
3) put <br> in front of the name
4) don't start that line with name:
5) use the &thinsp; character between the name and the ':'

etc.
Aug 27 2005
next sibling parent reply "Ben Hinkle" <ben.hinkle gmail.com> writes:
 /**
  * Returns an Image object that can then be painted on the screen.
  *
  * The url argument must specify an absolute URL. The name
  * argument is a specifier that is relative to the url argument.
  *
  * Params:
  *     url        an absolute URL giving the base location of the image
  *     name    the location of the image, relative to the url argument
  *
  * Returns:
  *                 the image at the specified URL
  * See:
  *                Image
  */


I now realize I typed "Return:" in my first post instead of "Returns:" (with 
an s). I don't know if I had Return because the Javadoc has  return or if I 
naturally removed the s because there is only one return value but probably 
many input parameters. In any case it's worth considering dropping the s 
from Returns.

ps- I use a monospaced font and the spacing looks messed up to me.
Aug 27 2005
parent reply "Walter" <newshound digitalmars.com> writes:
"Ben Hinkle" <ben.hinkle gmail.com> wrote in message
news:deqr6f$29a0$1 digitaldaemon.com...

 /**
  * Returns an Image object that can then be painted on the screen.
  *
  * The url argument must specify an absolute URL. The name
  * argument is a specifier that is relative to the url argument.
  *
  * Params:
  *     url        an absolute URL giving the base location of the image
  *     name    the location of the image, relative to the url argument
  *
  * Returns:
  *                 the image at the specified URL
  * See:
  *                Image
  */


 I now realize I typed "Return:" in my first post instead of "Returns:"


(with

 an s). I don't know if I had Return because the Javadoc has  return or if


I

 naturally removed the s because there is only one return value but


probably

 many input parameters. In any case it's worth considering dropping the s
 from Returns.


I prefer "returns" because then it reads "returns the image at the specified
URL".


 ps- I use a monospaced font and the spacing looks messed up to me.


That's because I composed it with a proportional font <g>.
Aug 27 2005
parent "Ben Hinkle" <ben.hinkle gmail.com> writes:
"Walter" <newshound digitalmars.com> wrote in message 
news:deqtkq$2aq0$2 digitaldaemon.com...

 "Ben Hinkle" <ben.hinkle gmail.com> wrote in message
 news:deqr6f$29a0$1 digitaldaemon.com...

 /**
  * Returns an Image object that can then be painted on the screen.
  *
  * The url argument must specify an absolute URL. The name
  * argument is a specifier that is relative to the url argument.
  *
  * Params:
  *     url        an absolute URL giving the base location of the image
  *     name    the location of the image, relative to the url argument
  *
  * Returns:
  *                 the image at the specified URL
  * See:
  *                Image
  */


 I now realize I typed "Return:" in my first post instead of "Returns:"


 (with

 an s). I don't know if I had Return because the Javadoc has  return or if


 I

 naturally removed the s because there is only one return value but


 probably

 many input parameters. In any case it's worth considering dropping the s
 from Returns.


 I prefer "returns" because then it reads "returns the image at the 
 specified
 URL".


Then can Params also become a verb like Takes or Needs or ... I dunno... 
Eats or something. It seems wierd that the other sections are nouns (well, 
except Include and Deprecated) but Returns is a verb. To me it clashes with 
Params most importantly.


 ps- I use a monospaced font and the spacing looks messed up to me.


 That's because I composed it with a proportional font <g>.


sneaky :-)
Aug 27 2005
prev sibling parent reply Bruno Medeiros <daiphoenixNO SPAMlycos.com> writes:
Walter wrote:

 
 It already looks like a typical manual page. I've never seen a manual page
 that used  's for emphasis (or any book printed since Gutenberg, for that
 matter).
 


But that is not the manual page. It is not the final doc output. And if 
we think it as such we might as well complain about those unnatural "/** 
  *  */  /// /++  +  +/",etc. symbols all over it.


And so one uses " "
for meta-language purposes because that's what the symbol will do
(specifying "sections" as Walter called it), and ":" for proper
human-language.


 
 
 A big goal for Ddoc (for lack of a better term!) is to have it look right in
 a proper human-language. I don't want it to look like computer code.
 


See answer above. It already has lots of code symbols like "/**  *  */ 
/// /++  +  +/", possibly others. Not to mention the doc is placed 
interlaced with computer code (the D language itself). And I frankly I 
don't see any problem with that, when one wants to see a more cleaner 
doc, just see the generated output doc.
(I sense this issue won't go much far than being a matter of personal 
opinion/taste)

-- 
Bruno Medeiros
Computer Science/Engineering student
Aug 28 2005
next sibling parent Hasan Aljudy <hasan.aljudy gmail.com> writes:
Bruno Medeiros wrote:

 Walter wrote:
 

 It already looks like a typical manual page. I've never seen a manual 
 page
 that used  's for emphasis (or any book printed since Gutenberg, for that
 matter).


 But that is not the manual page. It is not the final doc output. And if 
 we think it as such we might as well complain about those unnatural "/** 
  *  */  /// /++  +  +/",etc. symbols all over it.


<snip>

Which is why I prefer

/**
      this type of ocumentation
*/

over

/**
   *  this type
   */
Aug 28 2005
prev sibling parent "Walter" <newshound digitalmars.com> writes:
"Bruno Medeiros" <daiphoenixNO SPAMlycos.com> wrote in message
news:desch0$it4$1 digitaldaemon.com...

 (I sense this issue won't go much far than being a matter of personal
 opinion/taste)


You're right, at this point it's pretty obvious this isn't a technical
issue.
Aug 28 2005
prev sibling parent "Ben Hinkle" <ben.hinkle gmail.com> writes:
 /**
  * Returns an Image object that can then be painted on the screen.
  * The url argument must specify an absolute { link URL}. The name
  * argument is a specifier that is relative to the url argument.
  *
  *  param  url  an absolute URL giving the base location of the image
  *  param  name the location of the image, relative to the url argument
  *  return      the image at the specified URL
  *  see         Image
  */


A trivial conversion of the above keeping the same layout but replacing 
 param with spaces and putting a "Params:" on top and substituting  return 
and  see as appropriate:

/**
  * Returns an Image object that can then be painted on the screen.
  * The url argument must specify an absolute { link URL}. The name
  * argument is a specifier that is relative to the url argument.
  *
  * Params:
  *         url  an absolute URL giving the base location of the image
  *         name the location of the image, relative to the url argument
  * Return:      the image at the specified URL
  * See:         Image
  */

The version with the  s you have to look more carefully at the  params to 
parse them visually since at a glance they are very similar to the  return 
and  see. The D version is much easier for me to scan. If typing all the 
spaces in the params gets annoying I also think something like

/**
  * Returns an Image object that can then be painted on the screen.
  * The url argument must specify an absolute { link URL}. The name
  * argument is a specifier that is relative to the url argument.
  *
  * Params:
  *   url    an absolute URL giving the base location of the image
  *   name   the location of the image, relative to the url argument
  *
  * Return:  the image at the specified URL
  * See:     Image
  */

looks ok. There are probably other readable variations on the spacing, too.
Aug 27 2005
prev sibling next sibling parent reply Chris Sauls <ibisbasenji gmail.com> writes:
Ben Hinkle wrote:

  because  human-readable  text  doesn't  have  ats  in  it


I've probably just spent far too much time working in MOO-based environments,
but that was 
fairly readable to me...  Of course I'm also used to typing out command lines
like:
      sweep  players() has prop { ($attrs.notable), ($ftr_attr.notable)}
      who!  last with sort_ip

So don't go by me.  :)  Although one could "wrap" id's in  's.  Aka:

     ident  text
      more text

-- Chris Sauls
Aug 27 2005
parent "Walter" <newshound digitalmars.com> writes:
"Chris Sauls" <ibisbasenji gmail.com> wrote in message
news:deqin5$21ts$1 digitaldaemon.com...

 So don't go by me.  :)  Although one could "wrap" id's in  's.  Aka:

      ident  text
       more text


Sure, you could, but ... <g>

I used   in the first language I wrote (ABEL). It just never looked good.
Aug 27 2005
prev sibling parent reply Stewart Gordon <smjg_1998 yahoo.com> writes:
Ben Hinkle wrote:
<snip>

  because  human-readable  text  doesn't  have  ats  in  it


So whenever you insert an email address in a bit of text, humans cease 
to be able to read it?

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.
Sep 02 2005
parent Derek Parnell <derek psych.ward> writes:
On Fri, 02 Sep 2005 13:04:07 +0100, Stewart Gordon wrote:


 Ben Hinkle wrote:
 <snip>

  because  human-readable  text  doesn't  have  ats  in  it


 
 So whenever you insert an email address in a bit of text, humans cease 
 to be able to read it?


I suspect you have gone to an extreme that is not reasonable. An email
address has one ' ' symbol, whereas the example line has many such symbols.
Your point is discounted.

-- 
Derek Parnell
Melbourne, Australia
2/09/2005 11:53:37 PM
Sep 02 2005
prev sibling parent "Walter" <newshound digitalmars.com> writes:
"Bruno Medeiros" <daiphoenixNO SPAMlycos.com> wrote in message
news:deq5e5$1lrp$1 digitaldaemon.com...

 Speaking of which, and considering what Walter said on the other thread(

 needlessly and excessively klunky." ), what is the problem with Javadoc?

 ok to me (and is mostly similiar to that proposal). Is it because just
 the   symbol? (Ben Hinkle commented elsewhere on this thread that it was
 ugly) wth.. what's so ugly about the AT symbol? :o


javadoc isn't bad. It's those ugly   symbols <g>, which you'd never see in
written documentation.
Aug 27 2005
prev sibling next sibling parent reply "ElfQT" <dethjunk yahoo.com> writes:
"Walter" <newshound digitalmars.com> wrote in message 
news:depaee$fre$1 digitaldaemon.com...

 I've put up a strawman proposal for embedding documentation in comments at
 www.digitalmars.com/d/doc.html


Incredible!
I've left with only two arguments:
- Don't let two kind of parameter commenting. That will lead to confusion, 
or not, itt will be harder to switch between reading style one and style 
two.
I vote for the "header" style versus after each parameters, because there is 
also a return value to comment, and don't need to linebreaks at the 
parameters,

- the second: "all subsequent declarations at the same scope until another 
documentation comment at that scope is found"
/// documentation for C and D
class C { }

class D { }

From that you can't tell if class D is documented for real, or just been 
forgotten. That's a problem because compiler should falsely use the comment 
for subsequent undocumented class, and because then the compiler cannot 
require (generate warning/error) comment.

settings to signal errors on everything - on missing comment blocks also. 
That's the first circle of defense with 
unexperienced/lazy/forgetful/outsider coders.)
Also consider this:
Coder X writes:
/// documentation for C and D
class C { }

class D { }

Coder Y comes and continues the code with an overload of C:
/// documentation for C and D
class C { }

/// I've just inserted this little function
class C { int i }

class D { }

I don't see other way to resolve this, only to drop the referring to 
subsequent declarations - it is possible with referring unambiguously, but 
then you have to include something to refer to, and then refer to that 
later - that's too much and probably you'd fund it clumsy ;)

ElfQT
Aug 27 2005
parent reply "Walter" <newshound digitalmars.com> writes:
"ElfQT" <dethjunk yahoo.com> wrote in message
news:deqn6s$261i$1 digitaldaemon.com...

 "Walter" <newshound digitalmars.com> wrote in message
 news:depaee$fre$1 digitaldaemon.com...

 I've put up a strawman proposal for embedding documentation in comments




at

 www.digitalmars.com/d/doc.html


 Incredible!


Thanks!


 I've left with only two arguments:
 - Don't let two kind of parameter commenting. That will lead to confusion,
 or not, itt will be harder to switch between reading style one and style
 two.
 I vote for the "header" style versus after each parameters, because there


is

 also a return value to comment, and don't need to linebreaks at the
 parameters,


I think you're probably right. I have seen the other style used in contexts
where the programmers felt it to be a waste of keystrokes to type the
parameter names redundantly more than once all over again.


 - the second: "all subsequent declarations at the same scope until another
 documentation comment at that scope is found"
 /// documentation for C and D
 class C { }

 class D { }

 From that you can't tell if class D is documented for real, or just been
 forgotten. That's a problem because compiler should falsely use the


comment

 for subsequent undocumented class, and because then the compiler cannot
 require (generate warning/error) comment.


[...]

 I don't see other way to resolve this, only to drop the referring to
 subsequent declarations - it is possible with referring unambiguously, but
 then you have to include something to refer to, and then refer to that
 later - that's too much and probably you'd fund it clumsy ;)


The reason I put it in like that is sometimes one documents as a group a set
of related functions, such as:

    float sin(float)
    double sin(double)
    real sin(real)

and it's just feels stupid to have to separately document them with
cut/paste. I understand the problem you're describing, though, and I don't
see a solution to it other than "don't do that" :-(
Aug 27 2005
next sibling parent reply "ElfQT" <dethjunk yahoo.com> writes:
 I've left with only two arguments:
 - Don't let two kind of parameter commenting. That will lead to 
 confusion,
 or not, itt will be harder to switch between reading style one and style
 two.
 I vote for the "header" style versus after each parameters, because there


 is

 also a return value to comment, and don't need to linebreaks at the
 parameters,


 I think you're probably right. I have seen the other style used in 
 contexts
 where the programmers felt it to be a waste of keystrokes to type the
 parameter names redundantly more than once all over again.


Well, the editor should fill up the whole documentation space based on the 
definition,
and then there's no double typing.
Writing:
int Foo(int a, int b)
then adding "///" above it should generate (as the latest doc spec. says):
/** !Add brief summary here!
 *
 * !Add a longer description if needed!
 * Params:
 * a:    !add description
 * b:    !add description
 */


 The reason I put it in like that is sometimes one documents as a group a 
 set
 of related functions, such as:

    float sin(float)
    double sin(double)
    real sin(real)

 and it's just feels stupid to have to separately document them with
 cut/paste. I understand the problem you're describing, though, and I don't
 see a solution to it other than "don't do that" :-(


Then make a "documentation reference" element:
/// Doc for sin
float sin(float)
/// See: float sin(float)

, or at least signal "continuining scope comment" with an empty 
documentation:
/// Doc for sin
float sin(float)
///
double sin(double)
///
real sin(real)

(And in the second case, include a "compiler signals error on empty 
documentation" alongsidethe "compiler signals error on missing 
documentation" option for me ;) )
Aug 27 2005
parent reply "Walter" <newshound digitalmars.com> writes:
"ElfQT" <dethjunk yahoo.com> wrote in message
news:deqqml$290d$1 digitaldaemon.com...

 , or at least signal "continuining scope comment" with an empty
 documentation:
 /// Doc for sin
 float sin(float)
 ///
 double sin(double)
 ///
 real sin(real)


That's not bad.


 (And in the second case, include a "compiler signals error on empty
 documentation" alongsidethe "compiler signals error on missing
 documentation" option for me ;) )


<g>
Aug 27 2005
parent reply "Ben Hinkle" <ben.hinkle gmail.com> writes:
"Walter" <newshound digitalmars.com> wrote in message 
news:deqtkr$2aq0$3 digitaldaemon.com...

 "ElfQT" <dethjunk yahoo.com> wrote in message
 news:deqqml$290d$1 digitaldaemon.com...

 , or at least signal "continuining scope comment" with an empty
 documentation:
 /// Doc for sin
 float sin(float)
 ///
 double sin(double)
 ///
 real sin(real)


 That's not bad.


Since to me an empty doc comment isn't obvious it means "same as above" (to 
me it looks like someone forgot to say something) how about having a word 
there like Ditto (which means according to dictionary.com "same as stated 
above or before").
Aug 28 2005
parent "Walter" <newshound digitalmars.com> writes:
"Ben Hinkle" <ben.hinkle gmail.com> wrote in message
news:desd8s$je3$1 digitaldaemon.com...

 Since to me an empty doc comment isn't obvious it means "same as above"


(to

 me it looks like someone forgot to say something) how about having a word
 there like Ditto (which means according to dictionary.com "same as stated
 above or before").


Funny you say that, as I was just thinking that:
    /** ditto */
might do the trick. I guess great minds think alike!
Aug 28 2005
prev sibling next sibling parent Chris Sauls <ibisbasenji gmail.com> writes:
Walter wrote:

 "ElfQT" <dethjunk yahoo.com> wrote in message
 news:deqn6s$261i$1 digitaldaemon.com...

- the second: "all subsequent declarations at the same scope until another
documentation comment at that scope is found"
/// documentation for C and D
class C { }

class D { }

From that you can't tell if class D is documented for real, or just been
forgotten. That's a problem because compiler should falsely use the


 
 comment
 

for subsequent undocumented class, and because then the compiler cannot
require (generate warning/error) comment.


 
 [...]
 

I don't see other way to resolve this, only to drop the referring to
subsequent declarations - it is possible with referring unambiguously, but
then you have to include something to refer to, and then refer to that
later - that's too much and probably you'd fund it clumsy ;)


 
 
 The reason I put it in like that is sometimes one documents as a group a set
 of related functions, such as:
 
     float sin(float)
     double sin(double)
     real sin(real)
 
 and it's just feels stupid to have to separately document them with
 cut/paste. I understand the problem you're describing, though, and I don't
 see a solution to it other than "don't do that" :-(


One possible (albeit not beautiful) solution might be to allow braces in doc
comments, in 
the same sense as attribute blocks:








-- Chris Sauls
Aug 28 2005
prev sibling parent reply Daniel Siegmann <gandalf optonline.net> writes:
Walter wrote:

From that you can't tell if class D is documented for real, or just been
forgotten. That's a problem because compiler should falsely use the




<snip>

 The reason I put it in like that is sometimes one documents as a group a set
 of related functions, such as:
 
     float sin(float)
     double sin(double)
     real sin(real)
 
 and it's just feels stupid to have to separately document them with
 cut/paste. I understand the problem you're describing, though, and I don't
 see a solution to it other than "don't do that" :-(


I really don't like comments falling through. Much better to give some 
way to explicitly inherit a comment from something else.

For example, many times I'll be editing code written by someone else, 
which is not commented, but I'll add commenting to my own work. I 
wouldn't want that to end up falling through.

Perhaps you could include some sort of "inherit" tag, which could then 
specify the field/method/class/whatever to inherit the docs from?
Aug 31 2005
parent Chris Sauls <ibisbasenji gmail.com> writes:
Daniel Siegmann wrote:

 Walter wrote:
 

 From that you can't tell if class D is documented for real, or just been
 forgotten. That's a problem because compiler should falsely use the




 
 <snip>
 

 The reason I put it in like that is sometimes one documents as a group 
 a set
 of related functions, such as:

     float sin(float)
     double sin(double)
     real sin(real)

 and it's just feels stupid to have to separately document them with
 cut/paste. I understand the problem you're describing, though, and I 
 don't
 see a solution to it other than "don't do that" :-(


 
 
 I really don't like comments falling through. Much better to give some 
 way to explicitly inherit a comment from something else.
 
 For example, many times I'll be editing code written by someone else, 
 which is not commented, but I'll add commenting to my own work. I 
 wouldn't want that to end up falling through.
 
 Perhaps you could include some sort of "inherit" tag, which could then 
 specify the field/method/class/whatever to inherit the docs from?


Wouldn't something like this be so much simpler?











Or.








-- Chris Sauls
Sep 01 2005
prev sibling next sibling parent reply "John C" <johnch_atms hotmail.com> writes:
"Walter" <newshound digitalmars.com> wrote in message 
news:depaee$fre$1 digitaldaemon.com...

 I've put up a strawman proposal for embedding documentation in comments at
 www.digitalmars.com/d/doc.html


Lovely stuff so far. A few things:

1) Will we be able to add custom sections?
2) Can you add a "Property" section?
3) Will it recognise protection attributes?

A custom section could, for example, document what exceptions are thrown in 
a method.

Also, I wouldn't want private or package members to be visible in public 
documentation, or at least there should be a switch to turn such behaviour 
on and off.
Aug 27 2005
parent reply "Walter" <newshound digitalmars.com> writes:
"John C" <johnch_atms hotmail.com> wrote in message
news:deqq8l$28lg$1 digitaldaemon.com...

 1) Will we be able to add custom sections?


Currently, unrecognized sections are just passed through to the output
unchanged.


 2) Can you add a "Property" section?


?


 3) Will it recognise protection attributes?


Sure.


 A custom section could, for example, document what exceptions are thrown


in

 a method.

 Also, I wouldn't want private or package members to be visible in public
 documentation, or at least there should be a switch to turn such behaviour
 on and off.


Right.
Aug 27 2005
parent reply Michael <Michael_member pathlink.com> writes:
While Im sure this would be a great new feature, its not high on my list of
priorities for D. I would much rather see Walter working on getting his IDE
working with D. To this day there still isnt one IDE that has debugging and
intellisense (although various ones have each).

In article <derhht$2pm2$1 digitaldaemon.com>, Walter says...

"John C" <johnch_atms hotmail.com> wrote in message
news:deqq8l$28lg$1 digitaldaemon.com...

 1) Will we be able to add custom sections?


Currently, unrecognized sections are just passed through to the output
unchanged.


 2) Can you add a "Property" section?


?


 3) Will it recognise protection attributes?


Sure.


 A custom section could, for example, document what exceptions are thrown


in

 a method.

 Also, I wouldn't want private or package members to be visible in public
 documentation, or at least there should be a switch to turn such behaviour
 on and off.


Right.
Aug 29 2005
parent "ElfQT" <dethjunk yahoo.com> writes:
OT


 ... Walter working on getting his IDE
 working with D ... IDE that has debugging and
 intellisense...


Is that for real, or thats just your wish?
Is there an IDE on the way?
Aug 30 2005
prev sibling next sibling parent reply Freejack <freejack nowhere.net> writes:
On Sat, 27 Aug 2005 01:47:18 -0700, Walter wrote:


 I've put up a strawman proposal for embedding documentation in comments at
 www.digitalmars.com/d/doc.html


Have you considered going the whole route and adding formalized
annotations for Splint and ASIS like tools? Look at the Spark system from
Praxis High Integrity Systems (www.praxis-his.com/sparkada/)to see what I
mean.

Freejack
Aug 28 2005
next sibling parent reply "Walter" <newshound digitalmars.com> writes:
"Freejack" <freejack nowhere.net> wrote in message
news:pan.2005.08.28.17.31.04.603691 nowhere.net...

 On Sat, 27 Aug 2005 01:47:18 -0700, Walter wrote:


 I've put up a strawman proposal for embedding documentation in comments




at

 www.digitalmars.com/d/doc.html


 Have you considered going the whole route and adding formalized
 annotations for Splint and ASIS like tools? Look at the Spark system from
 Praxis High Integrity Systems (www.praxis-his.com/sparkada/)to see what I
 mean.


The link doesn't work?
Aug 30 2005
parent Freejack <freejack nowhere.net> writes:
On Tue, 30 Aug 2005 21:36:59 -0700, Walter wrote:


 
 "Freejack" <freejack nowhere.net> wrote in message
 news:pan.2005.08.28.17.31.04.603691 nowhere.net...

 On Sat, 27 Aug 2005 01:47:18 -0700, Walter wrote:


 I've put up a strawman proposal for embedding documentation in comments




 at

 www.digitalmars.com/d/doc.html


 Have you considered going the whole route and adding formalized
 annotations for Splint and ASIS like tools? Look at the Spark system from
 Praxis High Integrity Systems (www.praxis-his.com/sparkada/)to see what I
 mean.


 
 The link doesn't work?


Strange. It works from here. Hrrrmmm... Perhaps something a bit more
in-depth... Try http://www.acm.org/sigada/WG/asiswg/asiswg.html

Granted, this is an Ada extension, however the concept seems right up the
alley of the embedded documentation system you're proposing.

Also try http://www.praxis-his.com

Freejack
Aug 30 2005
prev sibling parent reply "Walter" <newshound digitalmars.com> writes:
"Freejack" <freejack nowhere.net> wrote in message
news:pan.2005.08.28.17.31.04.603691 nowhere.net...

 On Sat, 27 Aug 2005 01:47:18 -0700, Walter wrote:


 I've put up a strawman proposal for embedding documentation in comments




at

 www.digitalmars.com/d/doc.html


 Have you considered going the whole route and adding formalized
 annotations for Splint and ASIS like tools? Look at the Spark system from
 Praxis High Integrity Systems (www.praxis-his.com/sparkada/)to see what I
 mean.


It seems way beyond what we're doing here <g>.
Aug 31 2005
parent Freejack <freejack nowhere.net> writes:
On Wed, 31 Aug 2005 11:37:50 -0700, Walter wrote:


 
 "Freejack" <freejack nowhere.net> wrote in message
 news:pan.2005.08.28.17.31.04.603691 nowhere.net...

 On Sat, 27 Aug 2005 01:47:18 -0700, Walter wrote:


 I've put up a strawman proposal for embedding documentation in comments




 at

 www.digitalmars.com/d/doc.html


 Have you considered going the whole route and adding formalized
 annotations for Splint and ASIS like tools? Look at the Spark system from
 Praxis High Integrity Systems (www.praxis-his.com/sparkada/)to see what I
 mean.


 
 It seems way beyond what we're doing here <g>.


Probably. I wasn't suggesting creating an entire subsystem for that
specific purpose. I was thinking more along the lines of ASIS-lite. Just a
few generalized hooks into the system would be all that D needs, rather
than the whole hog that an Asis like specification would require. Later
on, others could come along and build on that foundation.

Just a thought.

Freejack
Aug 31 2005
prev sibling next sibling parent reply Niko Korhonen <niktheblak hotmail.com> writes:
Walter wrote:

 I've put up a strawman proposal for embedding documentation in comments at
 www.digitalmars.com/d/doc.html


Wonderful! This documentation scheme impressed me so that I instantly
converted my library's docs into this new proposed format.

The whole approach of providing as clutter-free scheme as possible is
definitely worth pursuing for, don't let the Javadoccers with their
crazy <p>'s and  -signs change your mind <g>

In any case I have a feeling that documenting D code will be much more
pleasant task from now on. Thanks!

--
Niko Korhonen
SW Developer
Aug 29 2005
parent clayasaurus <clayasaurus gmail.com> writes:
Niko Korhonen wrote:

 Walter wrote:
 

I've put up a strawman proposal for embedding documentation in comments at
www.digitalmars.com/d/doc.html


 
 
 Wonderful! This documentation scheme impressed me so that I instantly
 converted my library's docs into this new proposed format.
 
 The whole approach of providing as clutter-free scheme as possible is
 definitely worth pursuing for, don't let the Javadoccers with their
 crazy <p>'s and  -signs change your mind <g>
 
 In any case I have a feeling that documenting D code will be much more
 pleasant task from now on. Thanks!
 


At least much more easily documentable.


 --
 Niko Korhonen
 SW Developer
Aug 29 2005
prev sibling next sibling parent reply "Jonathan Oser Jr." <jdoser email.uophx.edu> writes:
	charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable

I'm not sure if this was mentioned earlier, I haven't read about it in =
the thread yet and I figure that it is worth mentioning.

There is an inline documentation system that (I feel) is worth taking a =
look at.  It seems to generate good documentation with a minimum of =
extra symbols and such.

It's called Natural Docs and you can read more at www.naturaldocs.org

Have fun,
Jon
  "Walter" <newshound digitalmars.com> wrote in message =
news:depaee$fre$1 digitaldaemon.com...
  I've put up a strawman proposal for embedding documentation in =
comments at
  www.digitalmars.com/d/doc.html
Aug 29 2005
parent Chris Sauls <ibisbasenji gmail.com> writes:
Its already been suggested to the NaturalDocs developers.  See here:
http://www.naturaldocs.org/languages.html

Under the heading: Getting Full Language Support

D is sixth down the list.  It isn't too completely different from Walter's
proposal -- and 
might be a worthy influence on it.  In any case its worthy sending in votes to
get D fully 
supported.

-- Chris Sauls

Jonathan Oser Jr. wrote:

 I'm not sure if this was mentioned earlier, I haven't read about it in 
 the thread yet and I figure that it is worth mentioning.
  
 There is an inline documentation system that (I feel) is worth taking a 
 look at.  It seems to generate good documentation with a minimum of 
 extra symbols and such.
  
 It's called Natural Docs and you can read more at www.naturaldocs.org 
 <http://www.naturaldocs.org>
  
 Have fun,
 Jon
 
     "Walter" <newshound digitalmars.com
     <mailto:newshound digitalmars.com>> wrote in message
     news:depaee$fre$1 digitaldaemon.com...
     I've put up a strawman proposal for embedding documentation in
     comments at
     www.digitalmars.com/d/doc.html <http://www.digitalmars.com/d/doc.html>
Aug 30 2005
prev sibling next sibling parent reply Bruno Medeiros <daiphoenixNO SPAMlycos.com> writes:
Walter wrote:

 I've put up a strawman proposal for embedding documentation in comments at
 www.digitalmars.com/d/doc.html
 
 


It just occurred to me, with this proposal, what tool would be used to 
generate the doc? Is there an existing one, or it would have to be created?

-- 
Bruno Medeiros
Computer Science/Engineering student
Aug 30 2005
parent "Regan Heath" <regan netwin.co.nz> writes:
On Tue, 30 Aug 2005 22:53:31 +0000, Bruno Medeiros  
<daiphoenixNO SPAMlycos.com> wrote:


 Walter wrote:

 I've put up a strawman proposal for embedding documentation in comments  
 at
 www.digitalmars.com/d/doc.html


 It just occurred to me, with this proposal, what tool would be used to  
 generate the doc? Is there an existing one, or it would have to be  
 created?


http://www.digitalmars.com/drn-bin/wwwnews?digitalmars.D/28157

Regan
Aug 30 2005
prev sibling next sibling parent reply =?iso-8859-1?q?Knud_S=F8rensen?= <12tkvvb02 sneakemail.com> writes:
What I am missing is a way to add the unit test to the 
documentation as examples.

Most auto-generated documents doesn't have enough examples.



On Sat, 27 Aug 2005 01:47:18 -0700, Walter wrote:


 I've put up a strawman proposal for embedding documentation in comments at
 www.digitalmars.com/d/doc.html
Aug 31 2005
parent reply "Walter" <newshound digitalmars.com> writes:
"Knud Sørensen" <12tkvvb02 sneakemail.com> wrote in message
news:pan.2005.08.31.09.46.08.415427 sneakemail.com...

 What I am missing is a way to add the unit test to the
 documentation as examples.

 Most auto-generated documents doesn't have enough examples.


True, but unit tests generally make for poor examples.
Aug 31 2005
parent reply Stewart Gordon <smjg_1998 yahoo.com> writes:
Walter wrote:

 "Knud Sørensen" <12tkvvb02 sneakemail.com> wrote in message
 news:pan.2005.08.31.09.46.08.415427 sneakemail.com...

 What I am missing is a way to add the unit test to the
 documentation as examples.

 Most auto-generated documents doesn't have enough examples.


 
 True, but unit tests generally make for poor examples.


But they don't have to!  Someone can write unittests that make good 
examples.  As well as, not instead of, typical unittests that are 
designed to check that the code is working in a number of cases and not 
as a demonstration of how to use the library.

The programmer would insert a documentation comment to indicate that a 
unittest is to be documented as an example.

Examples as unittests are also a form of self-documenting code, and an 
excellent way to test the documented examples to make sure they work.

Of course, at the basic level of this feature, the assert statements 
would show up in the example, and this may or may not be what one wants. 
    Even if we provide an option to strip assert statements from the 
documentation, there might be leftover for loops that did nothing but an 
assert on each element of an array in turn, or even other statements 
that don't really belong to the example but are solely to prepare data 
to assert against.  Maybe we should have a comment form to mark the end 
of an example or a section that should be excluded from the example.

Conversely, not all examples make good unittests.  For example, code 
that writes to a file or implements a GUI might not be desirable to 
write as a unittest.  And so we should also be able to include an 
example by putting it into the code as a comment or by referencing 
another code file.

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.
Sep 02 2005
next sibling parent reply Derek Parnell <derek psych.ward> writes:
On Fri, 02 Sep 2005 13:37:56 +0100, Stewart Gordon wrote:

[snip]

 Examples as unittests are also a form of self-documenting code, and an 
 excellent way to test the documented examples to make sure they work.


[snip]

 Conversely, not all examples make good unittests.


[snip]

Yes, it would be useful to nominate specific unittests to be examples. It
would also be useful to document other examples that are not unittests. For
instance, it would not be practical to execute unittests on a function that
displays a dialog window each time, or a function that reformats your hard
drive each time, etc ... But we still might want to show examples of its
usage.

-- 
Derek Parnell
Melbourne, Australia
2/09/2005 11:51:11 PM
Sep 02 2005
parent =?iso-8859-1?q?Knud_S=F8rensen?= <12tkvvb02 sneakemail.com> writes:
On Fri, 02 Sep 2005 23:58:41 +1000, Derek Parnell wrote:


 On Fri, 02 Sep 2005 13:37:56 +0100, Stewart Gordon wrote:
 
 [snip]

 Examples as unittests are also a form of self-documenting code, and an 
 excellent way to test the documented examples to make sure they work.


 [snip]

 Conversely, not all examples make good unittests.


 [snip]
 
 Yes, it would be useful to nominate specific unittests to be examples. It
 would also be useful to document other examples that are not unittests. For
 instance, it would not be practical to execute unittests on a function that
 displays a dialog window each time, or a function that reformats your hard
 drive each time, etc ... But we still might want to show examples of its
 usage.


Actually you can document this type of unit test as documentation.

What you could do is to abstract the interface on the window system or
driver, make a mock class with the same interface and then test your
code on the mock object. 

This type of test gives a lot of benefits. (search google for mock objects) 

Here it is important to remember that unit test should test the your code
is correct not that the window system or driver are correct. Such,
that you know that if the unit test fails it is your code or your unit
test which is in error.

If you need to test the window system you should run the unit test for
the window system or you functional tests.

Knud
Sep 04 2005
prev sibling parent =?iso-8859-1?q?Knud_S=F8rensen?= <12tkvvb02 sneakemail.com> writes:
You have some good points.

I where think maybe it could be at good idea to 
change the /++...+/ to document code.
So, that code between /++ ... +/ is both compiled and add to 
the documentation.

and /** .. */ is only added to the documentation as usual.

In this way we can easy add the code and unit test to the docs.
Sep 04 2005
prev sibling next sibling parent reply Stewart Gordon <smjg_1998 yahoo.com> writes:
Walter wrote:

 I've put up a strawman proposal for embedding documentation in comments at
 www.digitalmars.com/d/doc.html



documentation extractor if desired."

Do you mean that Doxygen supports this comment style now?  Or that it 
should degrade into something reasonable?  ISTM you'd need blank lines 
in places, otherwise you'd get stuff awkwardly run together like

This is my function. Params: fp File pointer name File name and more.

"int x,  // is for this"

Should this be /// rather than // ?

"HTML can be embedded into the documentation comments, and it will be 
passed through to the HTML output unchanged. However, since it is not 
necessarilly true that HTML will be the desired output format of the 
embedded documentation comment extractor, it is best to avoid using it 
where practical."

It ought to be specified that HTML character entities, at least &lt; 
&gt; &amp; will be rendered as their respective characters regardless of 
the output format.  That way, it would be possible to use these symbols 
in documentation and they will still work when generating documentation 
in non-HTML.

And will there be a way to group members into sections, as there is with 
Doxygen?

Spelling corrections:
liklihood -> likelihood
necessarilly -> necessarily

(Knowing you, s/illy/ily would make a half-decent spellchecker! :-) )

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.
Sep 02 2005
parent reply "Walter" <newshound digitalmars.com> writes:
"Stewart Gordon" <smjg_1998 yahoo.com> wrote in message
news:df9keh$kvi$1 digitaldaemon.com...

 Walter wrote:

 I've put up a strawman proposal for embedding documentation in comments




at

 www.digitalmars.com/d/doc.html



 documentation extractor if desired."

 Do you mean that Doxygen supports this comment style now?  Or that it
 should degrade into something reasonable?  ISTM you'd need blank lines
 in places, otherwise you'd get stuff awkwardly run together like


No, what I mean is that the Ddoc stuff is completely optional on the part of
the programmer. Comments will be ignored by the compiler, which means that
any documentation system that relies on embedded documentation comments can
be used and can use their entirely unique, and incompatible, format.


 This is my function. Params: fp File pointer name File name and more.

 "int x,  // is for this"

 Should this be /// rather than // ?


Yes.


 "HTML can be embedded into the documentation comments, and it will be
 passed through to the HTML output unchanged. However, since it is not
 necessarilly true that HTML will be the desired output format of the
 embedded documentation comment extractor, it is best to avoid using it
 where practical."

 It ought to be specified that HTML character entities, at least &lt;
 &gt; &amp; will be rendered as their respective characters regardless of
 the output format.  That way, it would be possible to use these symbols
 in documentation and they will still work when generating documentation
 in non-HTML.


Since the D source character set is unicode, any unicode characters can be
embedded. Using character entities will simply be copied to the output.


 And will there be a way to group members into sections, as there is with
 Doxygen?


Not in the first version. Ddoc isn't as advanced as Doxygen, and probably
won't become so.


 Spelling corrections:
 liklihood -> likelihood
 necessarilly -> necessarily


Got it, thanks!
Sep 02 2005
parent reply Stewart Gordon <Stewart_member pathlink.com> writes:
In article <dfa6th$190j$1 digitaldaemon.com>, Walter says...

"Stewart Gordon" <smjg_1998 yahoo.com> wrote in message
news:df9keh$kvi$1 digitaldaemon.com...


<snip>

 It ought to be specified that HTML character entities, at least &lt;
 &gt; &amp; will be rendered as their respective characters regardless of
 the output format.  That way, it would be possible to use these symbols
 in documentation and they will still work when generating documentation
 in non-HTML.


Since the D source character set is unicode, any unicode characters can be
embedded. Using character entities will simply be copied to the output.


<snip>

I don't see what that's to do with my point.  How does one embed a less than
sign then?

Stewart.
Sep 04 2005
parent reply "Walter" <newshound digitalmars.com> writes:
"Stewart Gordon" <Stewart_member pathlink.com> wrote in message
news:dfekd2$210h$1 digitaldaemon.com...

 In article <dfa6th$190j$1 digitaldaemon.com>, Walter says...

"Stewart Gordon" <smjg_1998 yahoo.com> wrote in message
news:df9keh$kvi$1 digitaldaemon.com...


 <snip>

 It ought to be specified that HTML character entities, at least &lt;
 &gt; &amp; will be rendered as their respective characters regardless






of

 the output format.  That way, it would be possible to use these symbols
 in documentation and they will still work when generating documentation
 in non-HTML.


Since the D source character set is unicode, any unicode characters can




be

embedded. Using character entities will simply be copied to the output.


 <snip>

 I don't see what that's to do with my point.  How does one embed a less


than

 sign then?


I am not understanding what the issue is? If you use < characters, they get
placed into the output. If that output is html, it may get interpreted as a
tag. Therefore, you should probably use &lt;, which will get echoed as &, l,
t, ; to the output.
Sep 04 2005
next sibling parent reply Stewart Gordon <smjg_1998 yahoo.com> writes:
Walter wrote:

 "Stewart Gordon" <Stewart_member pathlink.com> wrote in message 
 news:dfekd2$210h$1 digitaldaemon.com...

 In article <dfa6th$190j$1 digitaldaemon.com>, Walter says...

 "Stewart Gordon" <smjg_1998 yahoo.com> wrote in message 
 news:df9keh$kvi$1 digitaldaemon.com...


 <snip>

 It ought to be specified that HTML character entities, at least
 &lt; &gt; &amp; will be rendered as their respective 
 characters regardless of the output format.  That way, it would
 be possible to use these symbols in documentation and they 
 will still work when generating documentation in non-HTML.


 
 Since the D source character set is unicode, any unicode 
 characters can be embedded. Using character entities will simply 
 be copied to the output.


 <snip>
 
 I don't see what that's to do with my point.  How does one embed a 
 less than sign then?


 
 I am not understanding what the issue is? If you use < characters, 
 they get placed into the output. If that output is html, it may get 
 interpreted as a tag. Therefore, you should probably use &lt;, which 
 will get echoed as &, l, t, ; to the output.


If the output is not HTML, then the reader of the output will just see 
&, l, t, ; in the rendered document.  Under your current proposal, if 
someone wants to generate non-HTML documentation from source files 
written for HTML output, he/she/it will have to go through the source 
files replacing all &lt; with <.  And then when it's time to update the 
HTML documentation again, go through changing it back while having a 
care not to alter those that are part of the code itself.

It should be as possible as possible to write code documentation that 
works regardless of output format.  Of course converting all HTML tags 
into the target format isn't going to be easy, but translating &lt; into 
< if the output format isn't HTML certainly is.

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.
Sep 05 2005
parent "Walter Bright" <newshound digitalmars.com> writes:
"Stewart Gordon" <smjg_1998 yahoo.com> wrote in message
news:dfh6i0$119b$1 digitaldaemon.com...

 If the output is not HTML, then the reader of the output will just see
 &, l, t, ; in the rendered document.
 Under your current proposal, if
 someone wants to generate non-HTML documentation from source files
 written for HTML output, he/she/it will have to go through the source
 files replacing all &lt; with <.
 And then when it's time to update the
 HTML documentation again, go through changing it back while having a
 care not to alter those that are part of the code itself.

 It should be as possible as possible to write code documentation that
 works regardless of output format.  Of course converting all HTML tags
 into the target format isn't going to be easy, but translating &lt; into
 < if the output format isn't HTML certainly is.


You're right that converting named character entities isn't a big problem,
and that if the doc generator generates non-HTML output, it should make some
attempt to do so.
Sep 05 2005
prev sibling parent Charles Hixson <charleshixsn earthlink.net> writes:
Walter wrote:

 "Stewart Gordon" <Stewart_member pathlink.com> wrote in message
 news:dfekd2$210h$1 digitaldaemon.com...

 In article <dfa6th$190j$1 digitaldaemon.com>, Walter says...

 "Stewart Gordon" <smjg_1998 yahoo.com> wrote in message
 news:df9keh$kvi$1 digitaldaemon.com...


 <snip>

 It ought to be specified that HTML character entities, at least &lt;
 &gt; &amp; will be rendered as their respective characters regardless






 of

 the output format.  That way, it would be possible to use these symbols
 in documentation and they will still work when generating documentation
 in non-HTML.


 Since the D source character set is unicode, any unicode characters can




 be

 embedded. Using character entities will simply be copied to the output.


 <snip>

 I don't see what that's to do with my point.  How does one embed a less


 than

 sign then?


 
 I am not understanding what the issue is? If you use < characters, they get
 placed into the output. If that output is html, it may get interpreted as a
 tag. Therefore, you should probably use &lt;, which will get echoed as &, l,
 t, ; to the output.
 
 


Perhaps this is a place where (embedded) macros should be 
allowed, e.g.:

html = True;
static if (html == False)
{    /++ Micros:
          "<" ::= "&lt;"
      +/
}
else
{   // well, no else case is needed
}
Sep 11 2005
prev sibling next sibling parent reply pragma <EricAnderton youknowthedrill.yahoo> writes:
Walter wrote:

 I've put up a strawman proposal for embedding documentation in comments at
 www.digitalmars.com/d/doc.html
 
 


This looks like a great proposal.  The Ares working group has actually 
been around this topic a few times, and the consensus there was fairly 
close to what you've composed.  :)

If I may offer my $0.02:

- Is this just a style guide, or are you planning to give DMD (or a 
separate tool) the smarts to generate documentation?

- What will happen to symbols that are parsed, but do not have 
accompanying documentation?  Will they be emitted in the doc generation 
output?

- Won't there be a problem with nesting using the /+...+/ syntax for 
capturing comments?  IMHO, it might be best to just ignore that comment 
type and just use them for commenting out the other more 'sensitive' 
comment types.

- I know that there are bound to be some sharp criticisms for this but I 
strongly feel that providing intermediate output to XML would be a wise 
choice for a doc generator.  It would allow one to apply a stylesheet 
via a browser or third-party tool, to generate documentation in a whole 
host of formats (Plain-text, HTML, Postscript, LaTEX, etc).  Such 
intermediate XML files can also be further processed into 
crosss-references, indexes and such by additional stylesheet transforms.

That way if anyone doesn't like the way the standard doc generator 
writes HTML, they can easily take a different tact.  Not even Javadoc or 
  Doxygen lets us do that.

-- 
- EricAnderton at yahoo
Sep 03 2005
parent reply "Walter" <newshound digitalmars.com> writes:
"pragma" <EricAnderton youknowthedrill.yahoo> wrote in message
news:dfcqik$gfj$1 digitaldaemon.com...

 - Is this just a style guide,


For the moment, yes.


 or are you planning to give DMD (or a
 separate tool) the smarts to generate documentation?


It would be part of DMD, that way it can take advantage of DMD's symbol
table.


 - What will happen to symbols that are parsed, but do not have
 accompanying documentation?  Will they be emitted in the doc generation
 output?


They'll be there, too. Having an empty description for it will encourage
writing one <g>.


 - Won't there be a problem with nesting using the /+...+/ syntax for
 capturing comments?  IMHO, it might be best to just ignore that comment
 type and just use them for commenting out the other more 'sensitive'
 comment types.


I don't see the problem?


 - I know that there are bound to be some sharp criticisms for this but I
 strongly feel that providing intermediate output to XML would be a wise
 choice for a doc generator.  It would allow one to apply a stylesheet
 via a browser or third-party tool, to generate documentation in a whole
 host of formats (Plain-text, HTML, Postscript, LaTEX, etc).  Such
 intermediate XML files can also be further processed into
 crosss-references, indexes and such by additional stylesheet transforms.

 That way if anyone doesn't like the way the standard doc generator
 writes HTML, they can easily take a different tact.  Not even Javadoc or
   Doxygen lets us do that.


XML output is certainly possible. I tried to avoid in the specification what
the output format would be.
Sep 03 2005
parent reply pragma <EricAnderton youknowthedrill.yahoo> writes:
Thank you for answering my questions Walter. :)

Walter wrote:

- Won't there be a problem with nesting using the /+...+/ syntax for
capturing comments?  IMHO, it might be best to just ignore that comment
type and just use them for commenting out the other more 'sensitive'
comment types.


 
 
 I don't see the problem?


/++
+  Some documentation here
+
/++
+ More documentation here
+
+/
/**
* Even more documentation here
*/
+/

The problem is that the case isn't clearly documented.  Rather than 
introduce rules that may not be what the developer would expect.

The easiest way to "solve" this is to throw out nested (/+...+/) 
comments completely as to avoid this similar cases completely.  It would 
also give the developer a way to tell the doc generator to ignore 
otherwise "capturable" comment blocks (so we don't have to kludge things 
with a version() statement instead).

-- 
- EricAnderton at yahoo
Sep 04 2005
parent "Walter" <newshound digitalmars.com> writes:
"pragma" <EricAnderton youknowthedrill.yahoo> wrote in message
news:dfesml$27on$1 digitaldaemon.com...

 /++
 +  Some documentation here
 +
 /++
 + More documentation here
 +
 +/
 /**
 * Even more documentation here
 */
 +/

 The problem is that the case isn't clearly documented.  Rather than
 introduce rules that may not be what the developer would expect.


Comments appearing inside of doc comments will be simply echo'd to the
output. That will make it easy to do things like embed source text inside a
doc comment, as you'd just wrap it in /++ ... +/.
Sep 04 2005
prev sibling parent Peri Hankey <mpah thegreen.co.uk> writes:
Walter wrote:

 I've put up a strawman proposal for embedding documentation in comments at
 www.digitalmars.com/d/doc.html
 
 


This is to point out an alternative approach to documentation and source 
code. In the language machine (which is written in D and includes a d2d 
translator as one of its examples) I found it very useful to adopt a 
subset of the mediawiki (wikipedia) notation as the lexical form of 
input to the lmn metalanguage rule compiler.

In this approach, preformatted text (inset by at least one space) is 
treated as actual source, and everything else as comment, where the 
comment can include mediawiki markup.

This means that you can produce web pages directly from the source by 
applying the mediawiki ruleset, and it also means that you can put 
source directly onto a wiki and have it come out lokking fairly pretty - 
except that the mediawiki software doesn't treat the preformatted stuff 
as being also wrapped as <nowiki> </nowiki>. This seems to me pretty 
useful as enabling direct exchange of annotated source code fragments in 
a wiki.

I find that this approach is very natural and easy to use - you can see 
the results in (for example) the web page that is generated directly 
from the source text of the lmn metalanguage compiler front end:

http://languagemachine.sourceforge.net/lmn2xfe.html

Just a thought, in case it seems useful.

Peri

-- 
http://languagemachine.sourceforge.net - The language machine
Sep 05 2005