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