D - What about documentation syntax?
- OddesE (25/25) Jan 19 2002 How about some special syntax for documentation?
- Walter (8/33) Jan 19 2002 Being able to have both the documentation and the implementation code in...
- OddesE (35/41) Jan 19 2002 the
- Walter (6/16) Jan 19 2002 You're not forced to use HTML. There's no reason why you couldn't write ...
- OddesE (25/41) Jan 19 2002 and
- Russell Borogove (8/29) Jan 20 2002 So use:
- OddesE (54/83) Jan 20 2002 What do you mean?
- Karl Bochert (9/13) Jan 20 2002 I agree that such a tool is desireable, but I think it can
- Sean L. Palmer (7/10) Jan 21 2002 No, I do agree that it'd be nice to have some unique way to flag
- J. Daniel Smith (10/100) Jan 21 2002 If this D/XML (DML) idea catches on as an improved version of D-in-HTML,
- Sean L. Palmer (3/14) Jan 20 2002 What the HELL are you blabbering about? You need to back that remark up
- OddesE (24/38) Jan 20 2002 Dear Sean, what remark did you mean?
- Rajiv Bhagwat (9/50) Jan 20 2002 Guys, what you are talking about is just a special case of 'literate
- J. Daniel Smith (17/77) Jan 21 2002 Yes, I've thought about that along with the DML (D in XML) thread. If y...
- Sean L. Palmer (13/54) Jan 21 2002 Sorry, I meant the first one. And probably shouldn't have been so snapp...
How about some special syntax for documentation?
With this I mean something to support modern
documentation generating tools, such as JavaDoc,
that create documentation files, in HTML for example,
by parsing source code to read code structure and
documentation comments.
At the moment JavaDoc uses /** and */, but this is
more like a friday afternoon fix. Also, this creates a
problem, because many people avoid /* */ for normal
comments, because they don't nest and they want to use
them for easy removing of blocks of code.
I'd rather see a special language feature to support this
powerful way of documenting your code.
Something like:
documentation
{
documentation for the source code goes here.
}
Any thoughts?
--
Stijn
OddesE_XYZ hotmail.com
http://OddesE.cjb.net
__________________________________________
Remove _XYZ from my address when replying by mail
Jan 19 2002
Being able to have both the documentation and the implementation code in the
same file is a great idea. I am not too sold on the idea of doing it with
specialized comments. How D does this is much better - D code can be
embedded inside .html files. The documentation is done in html, the compiler
ignores that and just compiles the code.
www.digitalmars.com/d/html.html
"OddesE" <OddesE_XYZ hotmail.com> wrote in message
news:a2d0fr$1qvr$1 digitaldaemon.com...
How about some special syntax for documentation?
With this I mean something to support modern
documentation generating tools, such as JavaDoc,
that create documentation files, in HTML for example,
by parsing source code to read code structure and
documentation comments.
At the moment JavaDoc uses /** and */, but this is
more like a friday afternoon fix. Also, this creates a
problem, because many people avoid /* */ for normal
comments, because they don't nest and they want to use
them for easy removing of blocks of code.
I'd rather see a special language feature to support this
powerful way of documenting your code.
Something like:
documentation
{
documentation for the source code goes here.
}
Any thoughts?
--
Stijn
OddesE_XYZ hotmail.com
http://OddesE.cjb.net
__________________________________________
Remove _XYZ from my address when replying by mail
Jan 19 2002
"Walter" <walter digitalmars.com> wrote in message news:a2d4ks$1tdi$3 digitaldaemon.com...Being able to have both the documentation and the implementation code inthesame file is a great idea. I am not too sold on the idea of doing it with specialized comments. How D does this is much better - D code can be embedded inside .html files. The documentation is done in html, thecompilerignores that and just compiles the code. www.digitalmars.com/d/html.htmlMmm, no I don't agree. The documentation and code should indeed be in the same file, but I wouldn't want to distribute that file! I would want to use a tool to convert the documentation in the source file together with the code to normal documentation that can easily be distributed. JavaDoc uses .html as it's output format, but there are tools that are able to convert to .pdf or other document formats. Being forced to use HTML as the documentation format is something I wouldn't like. Also, tools like JavaDoc allow you to tweak the level of detail in the documentation, and create a browsable structure of files that document entire programs or class libs, even recreating the entire inheritance tree. On top of that is the fact that if you use the source in HTML feature to document your code, your products would have to be open source. Not that I don't like open-source, but sometimes it is just not possible. A future DDoc would probably generate XML files which can then be easily converted to other document formats, including HTML and PDF. I am just afraid that when a DDoc comes along it will adopt the JavaDoc /** and */ comments. Besides, documentation is an integral part of every program or API, so why not integrate it right into the language spec? -- Stijn OddesE_XYZ hotmail.com http://OddesE.cjb.net __________________________________________ Remove _XYZ from my address when replying by mail
Jan 19 2002
"OddesE" <OddesE_XYZ hotmail.com> wrote in message news:a2d675$1uf5$1 digitaldaemon.com...Being forced to use HTML as the documentation format is something I wouldn't like. Also, tools like JavaDoc allow you to tweak the level of detail in the documentation, and create a browsable structure of files that document entire programs or class libs, even recreating the entire inheritance tree.You're not forced to use HTML. There's no reason why you couldn't write and run "Ddoc" on your own specialized comment format.I am just afraid that when a DDoc comes along it will adopt the JavaDoc /** and */ comments. Besides, documentation is an integral part of every program or API, so why not integrate it right into the language spec?I just don't think funky comments should be anything other than whitespace to the language!
Jan 19 2002
"Walter" <walter digitalmars.com> wrote in message news:a2dd87$22rg$1 digitaldaemon.com..."OddesE" <OddesE_XYZ hotmail.com> wrote in message news:a2d675$1uf5$1 digitaldaemon.com...andBeing forced to use HTML as the documentation format is something I wouldn't like. Also, tools like JavaDoc allow you to tweak the level of detail in the documentation, and create a browsable structure of files that document entire programs or class libs, even recreating the entire inheritance tree.You're not forced to use HTML. There's no reason why you couldn't writerun "Ddoc" on your own specialized comment format.Ah, I'm sorry If I wasn't clear... I meant that the syntax documentation { Documentation for javadoc like tools } Would be like /** */ but then specialized. I didn't mean for anything within the braces to be interpreted by the compiler... Maybe it should be more like: /*documentation Documentation for javadoc like tools */ Or something... But I would like language support for something like this. -- Stijn OddesE_XYZ hotmail.com http://OddesE.cjb.net __________________________________________ Remove _XYZ from my address when replying by mailI am just afraid that when a DDoc comes along it will adopt the JavaDoc /** and */ comments. Besides, documentation is an integral part of every program or API, so why not integrate it right into the language spec?I just don't think funky comments should be anything other than whitespace to the language!
Jan 19 2002
OddesE wrote:
Ah, I'm sorry If I wasn't clear...
I meant that the syntax
documentation
{
Documentation for javadoc like tools
}
Would be like /** */ but then specialized.
I didn't mean for anything within the braces
to be interpreted by the compiler...
Maybe it should be more like:
/*documentation
Documentation for javadoc like tools
*/
Or something...
But I would like language support for something
like this.
So use:
version (Documentation)
{
...
}
:)
-RB
Jan 20 2002
"Russell Borogove" <kaleja estarcion.com> wrote in message news:3C4A90F8.5050409 estarcion.com...OddesE wrote:What do you mean? the version keyword is for code...Everything within it should be syntactically correct. If I would write something like: version (Documentation) { Name: MyFunc Descr.: Prints out the text "Hello World.\n" Parameter: - Result: - Exceptions: - } The compiler would signal an error. I could ofcourse write: version (Documentation) { /* Name: MyFunc Descr.: Prints out the text "Hello World.\n" Parameters: - Result: - Exceptions: - */ } But then what is the point? I would like some language support for documentation, not just comments, there is a difference between them. /*doc doc*/ would signal documentation. If you had a function like this: /*doc Name: MyFunc Descr.: Prints out the text "Hello World.\n" Parameters: - Result: - Exceptions: - doc*/ void MyFunc() { // Call printf to print out "Hello World.\n" printf ("Hello World.\n"); } You would be able to remove the function and its documentation from the program by placing normal comments /* */ around them. I think the javadoc invention /** */ proves that there is a need for something like this, but it seems that most of you don't agree. Ah well, just a thought. -- Stijn OddesE_XYZ hotmail.com http://OddesE.cjb.net __________________________________________ Remove _XYZ from my address when replying by mailAh, I'm sorry If I wasn't clear... I meant that the syntax documentation { Documentation for javadoc like tools } Would be like /** */ but then specialized. I didn't mean for anything within the braces to be interpreted by the compiler... Maybe it should be more like: /*documentation Documentation for javadoc like tools */ Or something... But I would like language support for something like this.So use: version (Documentation) { ... } :) -RB
Jan 20 2002
Karl Bochert <kbochert ix.netcom.com> On Sun, 20 Jan 2002 23:21:14 +0100, in D you wrote:I think the javadoc invention /** */ proves that there is a need for something like this, but it seems that most of you don't agree. Ah well, just a thought.I agree that such a tool is desireable, but I think it can be done as an add-on tool, independent of the compiler. The question is who defines the syntax? 1) Walter 'suggests' (blesses) a syntax. 2) The user group (us!) comes to a consensus. 3) Each tool creator rolls his/her own. I kind of like 2), which should, at least, generate much message traffic.
Jan 20 2002
"OddesE" <OddesE_XYZ hotmail.com> wrote in message news:a2ffcr$c8a$1 digitaldaemon.com...I think the javadoc invention /** */ proves that there is a need for something like this, but it seems that most of you don't agree. Ah well, just a thought.No, I do agree that it'd be nice to have some unique way to flag documentation (separately from comments and also separate from whatever method is used to turn off sections of code for debugging purposes) Not sure what it should be though. Sean
Jan 21 2002
If this D/XML (DML) idea catches on as an improved version of D-in-HTML, then you can just write your comments in any XML-compliant dialect you like, XHTML being one of those. Everything in the "d" namespace would be D code, so it would be fairly easy to strip out documentation. With DML, there is probalby going to be minimal need for a JavaDoc like tool since you can get the function name, arguments, etc. from the "d" XML elements. Dan "OddesE" <OddesE_XYZ hotmail.com> wrote in message news:a2ffcr$c8a$1 digitaldaemon.com..."Russell Borogove" <kaleja estarcion.com> wrote in message news:3C4A90F8.5050409 estarcion.com...OddesE wrote:What do you mean? the version keyword is for code...Everything within it should be syntactically correct. If I would write something like: version (Documentation) { Name: MyFunc Descr.: Prints out the text "Hello World.\n" Parameter: - Result: - Exceptions: - } The compiler would signal an error. I could ofcourse write: version (Documentation) { /* Name: MyFunc Descr.: Prints out the text "Hello World.\n" Parameters: - Result: - Exceptions: - */ } But then what is the point? I would like some language support for documentation, not just comments, there is a difference between them. /*doc doc*/ would signal documentation. If you had a function like this: /*doc Name: MyFunc Descr.: Prints out the text "Hello World.\n" Parameters: - Result: - Exceptions: - doc*/ void MyFunc() { // Call printf to print out "Hello World.\n" printf ("Hello World.\n"); } You would be able to remove the function and its documentation from the program by placing normal comments /* */ around them. I think the javadoc invention /** */ proves that there is a need for something like this, but it seems that most of you don't agree. Ah well, just a thought. -- Stijn OddesE_XYZ hotmail.com http://OddesE.cjb.net __________________________________________ Remove _XYZ from my address when replying by mailAh, I'm sorry If I wasn't clear... I meant that the syntax documentation { Documentation for javadoc like tools } Would be like /** */ but then specialized. I didn't mean for anything within the braces to be interpreted by the compiler... Maybe it should be more like: /*documentation Documentation for javadoc like tools */ Or something... But I would like language support for something like this.So use: version (Documentation) { ... } :) -RB
Jan 21 2002
Mmm, no I don't agree. ......<snip>...... On top of that is the fact that if you use the source in HTML feature to document your code, your products would have to be open source. Not that I don't like open-source, but sometimes it is just not possible.What the HELL are you blabbering about? You need to back that remark up with facts. Sean......<snip>...... -- Stijn OddesE_XYZ hotmail.com http://OddesE.cjb.net
Jan 20 2002
"Sean L. Palmer" <spalmer iname.com> wrote in message news:a2e7up$2kgh$1 digitaldaemon.com...Dear Sean, what remark did you mean?Mmm, no I don't agree. ......<snip>...... On top of that is the fact that if you use the source in HTML feature to document your code, your products would have to be open source. Not that I don't like open-source, but sometimes it is just not possible.What the HELL are you blabbering about? You need to back that remark up with facts. SeanIf this one, my argument is that if the source code is in the documentation, I can't distribute that documentation to others without revealing the source. You could ofcourse write some tool to strip out the source from the .html file, but then what is the point? I'd rather use some JavaDoc style tool to convert my source files to documentation files that I can distribute, preferably with the option to select the output format as .html, .pdf or whatever. I think the source-in-HTML feature is really cool for websites that want to demonstrate a little program on their website, but I don't think it is suitable for documenting large, possibly secret projects to people that have to *use* the code, but not see it.On top of that is the fact that if you use the source in HTML feature to document your code, your products would have to be open source.If this one, then I would have to say that there are many companies that keep their source private, such as Microsoft. -- Stijn OddesE_XYZ hotmail.com http://OddesE.cjb.net __________________________________________ Remove _XYZ from my address when replying by mailNot that I don't like open-source, but sometimes it is just not possible.
Jan 20 2002
Guys, what you are talking about is just a special case of 'literate programming', implemented and popularized by Donald Knuth ages ago. Web contains a lot of literature and actually usable tools (under all platforms) for doing it. Using a single language independent tool is a better idea than forcing such things in the language specs. - Rajiv "OddesE" <OddesE_XYZ hotmail.com> wrote in message news:a2fegt$bf1$1 digitaldaemon.com..."Sean L. Palmer" <spalmer iname.com> wrote in message news:a2e7up$2kgh$1 digitaldaemon.com...Dear Sean, what remark did you mean?Mmm, no I don't agree. ......<snip>...... On top of that is the fact that if you use the source in HTML feature to document your code, your products would have to be open source. Not that I don't like open-source, but sometimes it is just not possible.What the HELL are you blabbering about? You need to back that remark up with facts. SeanIf this one, my argument is that if the source code is in the documentation, I can't distribute that documentation to others without revealing the source. You could ofcourse write some tool to strip out the source from the .html file, but then what is the point? I'd rather use some JavaDoc style tool to convert my source files to documentation files that I can distribute, preferably with the option to select the output format as .html, .pdf or whatever. I think the source-in-HTML feature is really cool for websites that want to demonstrate a little program on their website, but I don't think it is suitable for documenting large, possibly secret projects to people that have to *use* the code, but not see it.On top of that is the fact that if you use the source in HTML feature to document your code, your products would have to be open source.If this one, then I would have to say that there are many companies that keep their source private, such as Microsoft. -- Stijn OddesE_XYZ hotmail.com http://OddesE.cjb.net __________________________________________ Remove _XYZ from my address when replying by mailNot that I don't like open-source, but sometimes it is just not possible.
Jan 20 2002
Yes, I've thought about that along with the DML (D in XML) thread. If you haven't heard about Knuth's ideas, take a look at http://sunburn.stanford.edu/~knuth/cweb.html I think the most significant difference is that the CTANGLE and CWEAVE processes are simplified by the use of XML and XSLT so you don't need any special software (assuming of course that you already have XML software available which is pretty much the case these days on Windows platforms). Of course to support some of the more nifty features of "web", there is probably a need for another XSLT tranform to turn a .DWEB file into .DML which could then turned into D code (perhaps internal to the compiler) using the D.XSL XSLT stylesheet. Dan "Rajiv Bhagwat" <dataflow vsnl.com> wrote in message news:a2gaq7$slq$1 digitaldaemon.com...Guys, what you are talking about is just a special case of 'literate programming', implemented and popularized by Donald Knuth ages ago. Web contains a lot of literature and actually usable tools (under allplatforms)for doing it. Using a single language independent tool is a better idea than forcingsuchthings in the language specs. - Rajiv "OddesE" <OddesE_XYZ hotmail.com> wrote in message news:a2fegt$bf1$1 digitaldaemon.com...up"Sean L. Palmer" <spalmer iname.com> wrote in message news:a2e7up$2kgh$1 digitaldaemon.com...Mmm, no I don't agree. ......<snip>...... On top of that is the fact that if you use the source in HTML feature to document your code, your products would have to be open source. Not that I don't like open-source, but sometimes it is just not possible.What the HELL are you blabbering about? You need to back that remarkwith facts. SeanDear Sean, what remark did you mean?If this one, my argument is that if the source code is in the documentation, I can't distribute that documentation to others without revealing the source. You could ofcourse write some tool to strip out the source from the .html file, but then what is the point? I'd rather use some JavaDoc style tool to convert my source files to documentation files that I can distribute, preferably with the option to select the output format as .html, .pdf or whatever. I think the source-in-HTML feature is really cool for websites that want to demonstrate a little program on their website, but I don't think it is suitable for documenting large, possibly secret projects to people that have to *use* the code, but not see it.On top of that is the fact that if you use the source in HTML feature to document your code, your products would have to be open source.If this one, then I would have to say that there are many companies that keep their source private, such as Microsoft. -- Stijn OddesE_XYZ hotmail.com http://OddesE.cjb.net __________________________________________ Remove _XYZ from my address when replying by mailNot that I don't like open-source, but sometimes it is just not possible.
Jan 21 2002
Sorry, I meant the first one. And probably shouldn't have been so snappy. ;) I don't see how using source embedded in HTML causes any project to have to be "open source". Documentation can always be extracted for external developers in any case. D is easy enough to parse that the documentation extractor could also grab the function parameter lists or whatever it needed, and omit the rest of the source. Maybe you're using the term "open-source" in a way that is different from what I understand the term to mean. Sean "OddesE" <OddesE_XYZ hotmail.com> wrote in message news:a2fegt$bf1$1 digitaldaemon.com..."Sean L. Palmer" <spalmer iname.com> wrote in message news:a2e7up$2kgh$1 digitaldaemon.com...Dear Sean, what remark did you mean?Mmm, no I don't agree. ......<snip>...... On top of that is the fact that if you use the source in HTML feature to document your code, your products would have to be open source. Not that I don't like open-source, but sometimes it is just not possible.What the HELL are you blabbering about? You need to back that remark up with facts. SeanIf this one, my argument is that if the source code is in the documentation, I can't distribute that documentation to others without revealing the source. You could ofcourse write some tool to strip out the source from the .html file, but then what is the point? I'd rather use some JavaDoc style tool to convert my source files to documentation files that I can distribute, preferably with the option to select the output format as .html, .pdf or whatever. I think the source-in-HTML feature is really cool for websites that want to demonstrate a little program on their website, but I don't think it is suitable for documenting large, possibly secret projects to people that have to *use* the code, but not see it.On top of that is the fact that if you use the source in HTML feature to document your code, your products would have to be open source.If this one, then I would have to say that there are many companies that keep their source private, such as Microsoft. -- Stijn OddesE_XYZ hotmail.com http://OddesE.cjb.net __________________________________________ Remove _XYZ from my address when replying by mailNot that I don't like open-source, but sometimes it is just not possible.
Jan 21 2002