digitalmars.D.announce - Embedded Documentation in Comments
- Walter (2/2) Aug 27 2005 I've put up a strawman proposal for embedding documentation in comments ...
- Vathix (3/6) Aug 27 2005 Page not found.
- Walter (3/9) Aug 27 2005 Oops. It's there now.
- Vathix (12/15) Aug 27 2005 Not bad. What I don't seem to like is the "Params:" alternate method of ...
- Ben Hinkle (7/22) Aug 27 2005 It's true that spacing is an issue but @ symbols are ugly and I'm glad
- Vathix (16/36) Aug 27 2005 All right, but that suggests you have to keep on adding more and more
- Ben Hinkle (3/41) Aug 27 2005 whoops - good point :-)
- Jason Mills (26/49) Aug 27 2005 Why not simply use : or - after each parameter. I haven't thought about
- Walter (7/17) Aug 27 2005 I see your point, but I don't like the @ business because it doesn't loo...
- Ben Hinkle (11/13) Aug 27 2005 Nice. Some thoughts:
- Walter (12/25) Aug 27 2005 at
- J Thomas (3/7) Aug 27 2005 Excelent ideas. Are you planning on having the compiler produce the
- Charles (4/12) Aug 27 2005 Yea it would.
- Walter (8/10) Aug 27 2005 Yes, since the power of a default documentation system that is installed...
- Hasan Aljudy (16/20) Aug 27 2005 Nice ideas, and the code/doc looks pretty clean too.
- Walter (11/23) Aug 27 2005 Yes, that doesn't look too hot even though it is more "pure", which is w...
- Ameer Armaly (4/6) Aug 27 2005 Looks good, especially since this type of info helps people understand t...
- Bruno Medeiros (11/14) Aug 27 2005 Speaking of which, and considering what Walter said on the other thread(...
- Ben Hinkle (2/5) Aug 27 2005 @because @human-readable @text @doesn't @have @ats @in @it
- James Dunne (12/17) Aug 27 2005 It was mentioned that identifiers would automatically be emphasized. I'...
- Walter (9/15) Aug 27 2005 or some
-
Dave
(2/7)
Aug 27 2005
What? Could you repeat that
- Bruno Medeiros (8/17) Aug 27 2005 ...Huh? What: you: said: does: not: make: sense: at: all:
- Ben Hinkle (10/24) Aug 27 2005 I was using "dramatic license" to make my point. For a more serious answ...
- Mike Parker (6/11) Aug 27 2005 But on the other hand, once you've worked with Java for a while the @
- jmjmak utu.invalid.fi (5/16) Aug 27 2005 Speaking of javadoc, I hope we're not reinventing the wheel here. Both j...
- Walter (11/15) Aug 27 2005 javadoc
- Ben Hinkle (13/23) Aug 27 2005 heh - I've never really liked how Javadoc looks. :-)
- Walter (4/15) Aug 27 2005 I think I'll have Ddoc issue a fatal error message if any attempt is mad...
- Walter (4/12) Aug 27 2005 Using a postfix : isn't any harder for computers, so the argument for @ ...
- Bruno Medeiros (6/10) Aug 27 2005 What argument about being easier or harder for computers? No one was
- Bruno Medeiros (46/58) Aug 27 2005 The following seems to me much more natural(better word: readable) :
- Walter (35/54) Aug 27 2005 I'd write it as this (with the caveat that it won't look quite right usi...
- Derek Parnell (7/8) Aug 27 2005 Before the name is locked in, how about 'Docter' ;-)
- Walter (3/4) Aug 27 2005 I like it!
- Ben Hinkle (6/21) Aug 27 2005 I now realize I typed "Return:" in my first post instead of "Returns:" (...
- Walter (8/29) Aug 27 2005 (with
- Ben Hinkle (7/39) Aug 27 2005 Then can Params also become a verb like Takes or Needs or ... I dunno......
- Bruno Medeiros (14/28) Aug 28 2005 But that is not the manual page. It is not the final doc output. And if
-
Hasan Aljudy
(10/21)
Aug 28 2005
- Walter (4/6) Aug 28 2005 You're right, at this point it's pretty obvious this isn't a technical
- Ben Hinkle (31/41) Aug 27 2005 A trivial conversion of the above keeping the same layout but replacing
- Chris Sauls (9/10) Aug 27 2005 I've probably just spent far too much time working in MOO-based environm...
-
Walter
(4/7)
Aug 27 2005
Sure, you could, but ...
- Stewart Gordon (13/14) Sep 02 2005 So whenever you insert an email address in a bit of text, humans cease
-
Walter
(4/11)
Aug 27 2005
javadoc isn't bad. It's those ugly @ symbols
, which you'd never see ... - ElfQT (39/41) Aug 27 2005 Incredible!
- Walter (18/43) Aug 27 2005 at
- ElfQT (28/50) Aug 27 2005 Well, the editor should fill up the whole documentation space based on t...
- Walter (4/15) Aug 27 2005 That's not bad.
- Ben Hinkle (6/17) Aug 28 2005 Since to me an empty doc comment isn't obvious it means "same as above" ...
- Walter (6/10) Aug 28 2005 (to
- Chris Sauls (10/45) Aug 28 2005 One possible (albeit not beautiful) solution might be to allow braces in...
- Derek Parnell (8/10) Aug 27 2005 Excellent start. Almost everything needed is in place. I'll give it a fe...
- ElfQT (2/5) Aug 27 2005 Wow, a lonely man, who puts practice before preach, experience before th...
- Derek Parnell (6/12) Aug 27 2005 Well, let's just say I carry a few 'battle scars'.
- Walter (5/11) Aug 27 2005 at
- Derek Parnell (7/21) Aug 27 2005 Just a little note, I used an 'e' deliberately so as to make 'Docter' mo...
- John Reimer (6/31) Aug 27 2005 I figured that your "Docter" spelling was intentional. It fits together...
- Walter (9/18) Aug 27 2005 more
- J C Calvarese (6/24) Aug 28 2005 or Docmeister
- Vathix (6/9) Aug 28 2005 Doculator
- Ben Hinkle (4/14) Aug 28 2005 dmdoc is the best I've seen so far. I hope Walter doesn't choose somethi...
- John Reimer (3/12) Aug 28 2005 "Docster" is good. :-)
- Freejack (6/8) Aug 28 2005 Have you considered going the whole route and adding formalized
- Walter (4/11) Aug 30 2005 at
- Derek Parnell (7/21) Aug 30 2005 Try http://www.praxis-his.com/sparkada/ instead ;-)
- Freejack (7/22) Aug 30 2005 Strange. It works from here. Hrrrmmm... Perhaps something a bit more
- Derek Parnell (12/31) Aug 31 2005 It doesn't work because the URL in your text, as interpreted by most
- Walter (4/11) Aug 31 2005 at
- Freejack (8/23) Aug 31 2005 Probably. I wasn't suggesting creating an entire subsystem for that
- Niko Korhonen (11/13) Aug 29 2005 Wonderful! This documentation scheme impressed me so that I instantly
- clayasaurus (2/21) Aug 29 2005
- Jonathan Oser Jr. (15/15) Aug 29 2005 charset="iso-8859-1"
- Chris Sauls (8/28) Aug 30 2005 Its already been suggested to the NaturalDocs developers. See here:
- Bruno Medeiros (6/10) Aug 30 2005 It just occurred to me, with this proposal, what tool would be used to
- Regan Heath (4/12) Aug 30 2005 http://www.digitalmars.com/drn-bin/wwwnews?digitalmars.D/28157
- =?iso-8859-1?q?Knud_S=F8rensen?= (4/6) Aug 31 2005 What I am missing is a way to add the unit test to the
- Walter (3/6) Aug 31 2005 True, but unit tests generally make for poor examples.
- Stewart Gordon (31/39) Sep 02 2005 But they don't have to! Someone can write unittests that make good
- =?iso-8859-1?q?Knud_S=F8rensen?= (7/7) Sep 04 2005 You have some good points.
- Stewart Gordon (34/36) Sep 02 2005 "# It should be possible for the user to use Doxygen or other
- Walter (13/39) Sep 02 2005 at
-
Stewart Gordon
(6/15)
Sep 04 2005
- Walter (9/24) Sep 04 2005 of
- Stewart Gordon (21/45) Sep 05 2005 If the output is not HTML, then the reader of the output will just see
- Walter Bright (5/18) Sep 05 2005 You're right that converting named character entities isn't a big proble...
- Charles Hixson (12/39) Sep 11 2005 Perhaps this is a place where (embedded) macros should be
- pragma (26/30) Sep 03 2005 This looks like a great proposal. The Ares working group has actually
- Walter (10/30) Sep 03 2005 For the moment, yes.
- Peri Hankey (24/28) Sep 05 2005 This is to point out an alternative approach to documentation and source...
I've put up a strawman proposal for embedding documentation in comments at www.digitalmars.com/d/doc.html
Aug 27 2005
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.htmlPage not found.
Aug 27 2005
"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:Oops. It's there now.I've put up a strawman proposal for embedding documentation in comments at www.digitalmars.com/d/doc.htmlPage not found.
Aug 27 2005
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.htmlNot 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
"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: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.I've put up a strawman proposal for embedding documentation in comments at www.digitalmars.com/d/doc.htmlNot 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.I agree properties should be special. Your idea of property get/set seems fine to me.
Aug 27 2005
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...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.On Sat, 27 Aug 2005 04:47:18 -0400, Walter <newshound digitalmars.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.I've put up a strawman proposal for embedding documentation in comments at www.digitalmars.com/d/doc.htmlNot 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.
Aug 27 2005
"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:whoops - good point :-)"Vathix" <chris dprogramming.com> wrote in message news:op.sv5uwjdol2lsvj esi...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.On Sat, 27 Aug 2005 04:47:18 -0400, Walter <newshound digitalmars.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.I've put up a strawman proposal for embedding documentation in comments at www.digitalmars.com/d/doc.htmlNot 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.
Aug 27 2005
Vathix wrote:On Sat, 27 Aug 2005 08:13:28 -0400, Ben Hinkle <ben.hinkle gmail.com> wrote: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. JasonIt'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
"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
"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.htmlNice. 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
"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...atI've put up a strawman proposal for embedding documentation in commentsstuffwww.digitalmars.com/d/doc.htmlNice. Some thoughts: - how about also having a License: section or something for any legalthat users need to know about.That's a good idea.- allowing a wiki markup instead of embedded html solves the problem ofjusthow 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 putinCode.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
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
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:atI've put up a strawman proposal for embedding documentation in commentswww.digitalmars.com/d/doc.html
Aug 27 2005
"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
Walter wrote:I've put up a strawman proposal for embedding documentation in comments at www.digitalmars.com/d/doc.htmlNice 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
"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
"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.htmlLooks 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
Walter wrote:I've put up a strawman proposal for embedding documentation in comments at www.digitalmars.com/d/doc.htmlSpeaking 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
[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? :obecause human-readable text doesn't have ats in it
Aug 27 2005
In article <deq7p5$1o63$1 digitaldaemon.com>, Ben Hinkle says...[snip]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(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? :obecause human-readable text doesn't have ats in it
Aug 27 2005
"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 someother common english term that you'd use in your docs... I think aspecialmarker character should be used to deliniate identifiers from regular documentation. It doesn't have to be . How about placing parens orcurliesaround 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
In article <deq7p5$1o63$1 digitaldaemon.com>, Ben Hinkle says...[snip]What? Could you repeat that <g>(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? :obecause human-readable text doesn't have ats in it
Aug 27 2005
Ben Hinkle wrote:[snip]...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(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? :obecause human-readable text doesn't have ats in it
Aug 27 2005
"Bruno Medeiros" <daiphoenixNO SPAMlycos.com> wrote in message news:deqd0j$1rq5$1 digitaldaemon.com...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.[snip]...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.(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? :obecause human-readable text doesn't have ats in it
Aug 27 2005
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
In article <deqfvm$1upi$1 digitaldaemon.com>, Mike Parker says...Ben Hinkle wrote: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.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
<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. Bothjavadocand doxygen use a well known documentation syntax. Doxygen even supports d(notcompletely 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
"Mike Parker" <aldacron71 yahoo.com> wrote in message news:deqfvm$1upi$1 digitaldaemon.com...Ben Hinkle wrote: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.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
"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
"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
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
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
"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 in front of the name 3) put <br> in front of the name 4) don't start that line with name: 5) use the   character between the name and the ':' etc.
Aug 27 2005
On Sat, 27 Aug 2005 15:04:38 -0700, Walter wrote: [snip]A big goal for Ddoc (for lack of a better term!)Before the name is locked in, how about 'Docter' ;-) -- Derek Parnell Melbourne, Australia 28/08/2005 8:41:51 AM
Aug 27 2005
"Derek Parnell" <derek psych.ward> wrote in message news:leskatvqa7ub$.1gbohdes95d3h$.dlg 40tude.net...Before the name is locked in, how about 'Docter' ;-)I like it!
Aug 27 2005
/** * 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
"Ben Hinkle" <ben.hinkle gmail.com> wrote in message news:deqr6f$29a0$1 digitaldaemon.com...(with/** * 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:"an s). I don't know if I had Return because the Javadoc has return or ifInaturally removed the s because there is only one return value butprobablymany 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
"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...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.(with/** * 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:"an s). I don't know if I had Return because the Javadoc has return or ifInaturally removed the s because there is only one return value butprobablymany 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".sneaky :-)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
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.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 studentAnd 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.
Aug 28 2005
Bruno Medeiros wrote:Walter wrote:<snip> Which is why I prefer /** this type of ocumentation */ over /** * this type */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.
Aug 28 2005
"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
/** * 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
Ben Hinkle wrote:because human-readable text doesn't have ats in itI'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
"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 textSure, you could, but ... <g> I used in the first language I wrote (ABEL). It just never looked good.
Aug 27 2005
Ben Hinkle wrote: <snip>because human-readable text doesn't have ats in itSo 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
"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? :ojavadoc isn't bad. It's those ugly symbols <g>, which you'd never see in written documentation.
Aug 27 2005
"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.htmlIncredible! 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
"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...atI've put up a strawman proposal for embedding documentation in commentsThanks!www.digitalmars.com/d/doc.htmlIncredible!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 thereisalso 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 thecommentfor 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
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 */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 thereisalso 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 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
"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
"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...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")., 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.
Aug 28 2005
"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"(tome 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
Walter wrote:"ElfQT" <dethjunk yahoo.com> wrote in message news:deqn6s$261i$1 digitaldaemon.com...One possible (albeit not beautiful) solution might be to allow braces in doc comments, in the same sense as attribute blocks: -- Chris Sauls- 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 thecommentfor 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 28 2005
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.htmlExcellent start. Almost everything needed is in place. I'll give it a few more hours to sink in - maybe I'll start using it to see how it 'fits' before I comment much more. -- Derek Parnell Melbourne, Australia 28/08/2005 8:40:04 AM
Aug 27 2005
Excellent start. Almost everything needed is in place. I'll give it a few more hours to sink in - maybe I'll start using it to see how it 'fits' before I comment much more.Wow, a lonely man, who puts practice before preach, experience before theory ;)
Aug 27 2005
On Sun, 28 Aug 2005 00:52:35 +0200, ElfQT wrote:Well, let's just say I carry a few 'battle scars'. -- Derek Parnell Melbourne, Australia 28/08/2005 9:11:41 AMExcellent start. Almost everything needed is in place. I'll give it a few more hours to sink in - maybe I'll start using it to see how it 'fits' before I comment much more.Wow, a lonely man, who puts practice before preach, experience before theory ;)
Aug 27 2005
"Derek Parnell" <derek psych.ward> wrote in message news:lehj9jkn6tik$.bapa4d70t2fb$.dlg 40tude.net...On Sat, 27 Aug 2005 01:47:18 -0700, Walter wrote:atI've put up a strawman proposal for embedding documentation in commentsThe neato thing is "Doctor" doesn't need to even exist before one starts using that style.www.digitalmars.com/d/doc.htmlExcellent start. Almost everything needed is in place. I'll give it a few more hours to sink in - maybe I'll start using it to see how it 'fits' before I comment much more.
Aug 27 2005
On Sat, 27 Aug 2005 16:35:06 -0700, Walter wrote:"Derek Parnell" <derek psych.ward> wrote in message news:lehj9jkn6tik$.bapa4d70t2fb$.dlg 40tude.net...Just a little note, I used an 'e' deliberately so as to make 'Docter' more grep-able, but whatever! -- Derek Parnell Melbourne, Australia 28/08/2005 10:44:52 AMOn Sat, 27 Aug 2005 01:47:18 -0700, Walter wrote:atI've put up a strawman proposal for embedding documentation in commentsThe neato thing is "Doctor" doesn't need to even exist before one starts using that style.www.digitalmars.com/d/doc.htmlExcellent start. Almost everything needed is in place. I'll give it a few more hours to sink in - maybe I'll start using it to see how it 'fits' before I comment much more.
Aug 27 2005
Derek Parnell wrote:On Sat, 27 Aug 2005 16:35:06 -0700, Walter wrote:I figured that your "Docter" spelling was intentional. It fits together "doc" and "ter" like a modifier for a verb to make it a noun (almost like "fish-er" or "bat-ter". It had an added humorous touch of sounding like "Doctor." -JJR"Derek Parnell" <derek psych.ward> wrote in message news:lehj9jkn6tik$.bapa4d70t2fb$.dlg 40tude.net...Just a little note, I used an 'e' deliberately so as to make 'Docter' more grep-able, but whatever!On Sat, 27 Aug 2005 01:47:18 -0700, Walter wrote:atI've put up a strawman proposal for embedding documentation in commentsThe neato thing is "Doctor" doesn't need to even exist before one starts using that style.www.digitalmars.com/d/doc.htmlExcellent start. Almost everything needed is in place. I'll give it a few more hours to sink in - maybe I'll start using it to see how it 'fits' before I comment much more.
Aug 27 2005
"John Reimer" <terminal.node gmail.com> wrote in message news:der9mm$2iuj$1 digitaldaemon.com...Derek Parnell wrote:moreThe neato thing is "Doctor" doesn't need to even exist before one starts using that style.Just a little note, I used an 'e' deliberately so as to make 'Docter'Ok, I see that. But I'm concerned that people will fail to recognize that, leading to confusion. It's like I knew a person named Gregg once. He spent most of his life correcting other peoples' spelling of his name. Another fellow's last name was Hogg. He spent most of his life correcting other peoples' pronounciation of his name (he claimed it was pronounced "hoag").grep-able, but whatever!I figured that your "Docter" spelling was intentional. It fits together "doc" and "ter" like a modifier for a verb to make it a noun (almost like "fish-er" or "bat-ter". It had an added humorous touch of sounding like "Doctor.""Docster" might work? On second thought, yuk.
Aug 27 2005
In article <derhht$2pm2$2 digitaldaemon.com>, Walter says..."John Reimer" <terminal.node gmail.com> wrote in message news:der9mm$2iuj$1 digitaldaemon.com...or Docmeister or Docinator If it's built into DMD, I'm not sure we really need a special name for it. Couldn't we just call it D-style documentation. jcc7Derek Parnell wrote:moreThe neato thing is "Doctor" doesn't need to even exist before one starts using that style.Just a little note, I used an 'e' deliberately so as to make 'Docter'Ok, I see that. But I'm concerned that people will fail to recognize that, leading to confusion. It's like I knew a person named Gregg once. He spent most of his life correcting other peoples' spelling of his name. Another fellow's last name was Hogg. He spent most of his life correcting other peoples' pronounciation of his name (he claimed it was pronounced "hoag").grep-able, but whatever!I figured that your "Docter" spelling was intentional. It fits together "doc" and "ter" like a modifier for a verb to make it a noun (almost like "fish-er" or "bat-ter". It had an added humorous touch of sounding like "Doctor.""Docster" might work? On second thought, yuk.
Aug 28 2005
Doculator Docalicious Doctastic Cod What's up Doc DMDoc"Docster" might work? On second thought, yuk.or Docmeister or Docinator
Aug 28 2005
"Vathix" <chris dprogramming.com> wrote in message news:op.sv71ukr2l2lsvj esi...dmdoc is the best I've seen so far. I hope Walter doesn't choose something with upper case in it.Doculator Docalicious Doctastic Cod What's up Doc DMDoc"Docster" might work? On second thought, yuk.or Docmeister or Docinator
Aug 28 2005
Walter wrote:"Docster" is good. :-) -JJRI figured that your "Docter" spelling was intentional. It fits together "doc" and "ter" like a modifier for a verb to make it a noun (almost like "fish-er" or "bat-ter". It had an added humorous touch of sounding like "Doctor.""Docster" might work? On second thought, yuk.
Aug 28 2005
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.htmlHave 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
"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:atI've put up a strawman proposal for embedding documentation in commentsThe link doesn't work?www.digitalmars.com/d/doc.htmlHave 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.
Aug 30 2005
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...Try http://www.praxis-his.com/sparkada/ instead ;-) -- Derek (skype: derek.j.parnell) Melbourne, Australia 31/08/2005 3:11:12 PMOn Sat, 27 Aug 2005 01:47:18 -0700, Walter wrote:atI've put up a strawman proposal for embedding documentation in commentsThe link doesn't work?www.digitalmars.com/d/doc.htmlHave 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.
Aug 30 2005
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...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 FreejackOn Sat, 27 Aug 2005 01:47:18 -0700, Walter wrote:atI've put up a strawman proposal for embedding documentation in commentsThe link doesn't work?www.digitalmars.com/d/doc.htmlHave 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.
Aug 30 2005
On Wed, 31 Aug 2005 00:36:53 -0400, Freejack wrote:On Tue, 30 Aug 2005 21:36:59 -0700, Walter wrote:It doesn't work because the URL in your text, as interpreted by most newsreaders, is 'www.praxis-his.com/sparkada/)to' rather than 'www.praxis-his.com/sparkada/' -- Derek (skype: derek.j.parnell) Melbourne, Australia 31/08/2005 6:54:47 PM"Freejack" <freejack nowhere.net> wrote in message news:pan.2005.08.28.17.31.04.603691 nowhere.net...Strange. It works from here. Hrrrmmm...On Sat, 27 Aug 2005 01:47:18 -0700, Walter wrote:atI've put up a strawman proposal for embedding documentation in commentsThe link doesn't work?www.digitalmars.com/d/doc.htmlHave 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.
Aug 31 2005
"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:atI've put up a strawman proposal for embedding documentation in commentsIt seems way beyond what we're doing here <g>.www.digitalmars.com/d/doc.htmlHave 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.
Aug 31 2005
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...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. FreejackOn Sat, 27 Aug 2005 01:47:18 -0700, Walter wrote:atI've put up a strawman proposal for embedding documentation in commentsIt seems way beyond what we're doing here <g>.www.digitalmars.com/d/doc.htmlHave 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.
Aug 31 2005
Walter wrote:I've put up a strawman proposal for embedding documentation in comments at www.digitalmars.com/d/doc.htmlWonderful! 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
Niko Korhonen wrote:Walter wrote:At least much more easily documentable.I've put up a strawman proposal for embedding documentation in comments at www.digitalmars.com/d/doc.htmlWonderful! 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
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
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
Walter wrote:I've put up a strawman proposal for embedding documentation in comments at www.digitalmars.com/d/doc.htmlIt 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
On Tue, 30 Aug 2005 22:53:31 +0000, Bruno Medeiros <daiphoenixNO SPAMlycos.com> wrote:Walter wrote:http://www.digitalmars.com/drn-bin/wwwnews?digitalmars.D/28157 ReganI've put up a strawman proposal for embedding documentation in comments at www.digitalmars.com/d/doc.htmlIt 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?
Aug 30 2005
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
"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
Walter wrote:"Knud Sørensen" <12tkvvb02 sneakemail.com> wrote in message news:pan.2005.08.31.09.46.08.415427 sneakemail.com...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.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.
Sep 02 2005
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
Walter wrote:I've put up a strawman proposal for embedding documentation in comments at www.digitalmars.com/d/doc.htmldocumentation 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 < > & 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
"Stewart Gordon" <smjg_1998 yahoo.com> wrote in message news:df9keh$kvi$1 digitaldaemon.com...Walter wrote:atI've put up a strawman proposal for embedding documentation in commentsNo, 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.www.digitalmars.com/d/doc.htmldocumentation 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 likeThis 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 < > & 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 -> necessarilyGot it, thanks!
Sep 02 2005
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><snip> I don't see what that's to do with my point. How does one embed a less than sign then? Stewart.It ought to be specified that HTML character entities, at least < > & 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.
Sep 04 2005
"Stewart Gordon" <Stewart_member pathlink.com> wrote in message news:dfekd2$210h$1 digitaldaemon.com...In article <dfa6th$190j$1 digitaldaemon.com>, Walter says...of"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 < > & will be rendered as their respective characters regardlessbethe 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 canthanembedded. 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 lesssign 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 <, which will get echoed as &, l, t, ; to the output.
Sep 04 2005
Walter wrote:"Stewart Gordon" <Stewart_member pathlink.com> wrote in message news:dfekd2$210h$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 < 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 < 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.In article <dfa6th$190j$1 digitaldaemon.com>, Walter says...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 <, which will get echoed as &, l, t, ; to the output."Stewart Gordon" <smjg_1998 yahoo.com> wrote in message news:df9keh$kvi$1 digitaldaemon.com...<snip><snip> I don't see what that's to do with my point. How does one embed a less than sign then?It ought to be specified that HTML character entities, at least < > & 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.
Sep 05 2005
"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 < 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 < 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
Walter wrote:"Stewart Gordon" <Stewart_member pathlink.com> wrote in message news:dfekd2$210h$1 digitaldaemon.com...Perhaps this is a place where (embedded) macros should be allowed, e.g.: html = True; static if (html == False) { /++ Micros: "<" ::= "<" +/ } else { // well, no else case is needed }In article <dfa6th$190j$1 digitaldaemon.com>, Walter says...of"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 < > & will be rendered as their respective characters regardlessbethe 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 canthanembedded. 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 lesssign 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 <, which will get echoed as &, l, t, ; to the output.
Sep 11 2005
Walter wrote:I've put up a strawman proposal for embedding documentation in comments at www.digitalmars.com/d/doc.htmlThis 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
"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
Thank you for answering my questions Walter. :) Walter wrote:/++ + 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- 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?
Sep 04 2005
"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
Walter wrote:I've put up a strawman proposal for embedding documentation in comments at www.digitalmars.com/d/doc.htmlThis 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