www.digitalmars.com         C & C++   DMDScript  

D - What about documentation syntax?

reply "OddesE" <OddesE_XYZ hotmail.com> writes:
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
parent reply "Walter" <walter digitalmars.com> writes:
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
parent reply "OddesE" <OddesE_XYZ hotmail.com> writes:
"Walter" <walter digitalmars.com> wrote in message
news:a2d4ks$1tdi$3 digitaldaemon.com...
 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
Mmm, 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
next sibling parent reply "Walter" <walter digitalmars.com> writes:
"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
parent reply "OddesE" <OddesE_XYZ hotmail.com> writes:
"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...
 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!
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 mail
Jan 19 2002
parent reply Russell Borogove <kaleja estarcion.com> writes:
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
parent reply "OddesE" <OddesE_XYZ hotmail.com> writes:
"Russell Borogove" <kaleja estarcion.com> wrote in message
news:3C4A90F8.5050409 estarcion.com...
 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
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 mail
Jan 20 2002
next sibling parent Karl Bochert <kbochert ix.netcom.com> writes:
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
prev sibling next sibling parent "Sean L. Palmer" <spalmer iname.com> writes:
"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
prev sibling parent "J. Daniel Smith" <j_daniel_smith deja.com> writes:
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:


 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
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 mail
Jan 21 2002
prev sibling parent reply "Sean L. Palmer" <spalmer iname.com> writes:
 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
parent reply "OddesE" <OddesE_XYZ hotmail.com> writes:
"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 remark up with facts. Sean
Dear Sean, what remark did you mean?
 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, 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.
 Not that I don't like open-source, but
 sometimes it is just not possible.
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 mail
Jan 20 2002
next sibling parent reply "Rajiv Bhagwat" <dataflow vsnl.com> writes:
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...
 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
Dear Sean, what remark did you mean?
 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, 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.
 Not that I don't like open-source, but
 sometimes it is just not possible.
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 mail
Jan 20 2002
parent "J. Daniel Smith" <j_daniel_smith deja.com> writes:
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 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...
 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
Dear Sean, what remark did you mean?
 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, 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.
 Not that I don't like open-source, but
 sometimes it is just not possible.
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 mail
Jan 21 2002
prev sibling parent "Sean L. Palmer" <spalmer iname.com> writes:
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...
 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
Dear Sean, what remark did you mean?
 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, 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.
 Not that I don't like open-source, but
 sometimes it is just not possible.
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 mail
Jan 21 2002