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

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
>
>
>

"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

"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!

"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

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

> 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

"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

"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

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.