"Jason Mills" <jmills@cs.mun.ca> wrote in message news:3D355879.2060807@cs.mun.ca...

> In addition I can
> use the same text editor, configured the way I like, for any programming
> language I happen to be coding in at the moment, including D, while
> others using IDE's often have to learn a new editor for each different
> IDE.
>
> Jason

I note that you said "often", but there are many multi-language IDE's out there including "PC-grasp", "epsilon", "Scintilla" and also all those built in ones that came with UNIX (which I forget). It's a matter of preference if you use an IDE or not. IDE's simplify a lot of common tasks such as compilation. Having to write/modify a make file everytime you write program is just another task you add to add to do. Alternatively having to workout how to make a multi-language IDE D proficient is another big task also (Although it only needs to be done once).

Most IDE's use interface standards which makes switchingfrom one IDE to another easier. The only real problems faced is learning how to set things up and how to use the language specific tool (which you probably don't need anyway).

I guess you are all right... :)
When writing the document I was also running into
the fact that the xml is too verbose to type by hand.
I think Juarez solution, parse source code comments,
generate intermediate xml and from that generate
resulting documentation, is best. I just wanted to show
another way of doing it.
But there still remain some issues with Juarez'
proposed syntax. Especially when to know if a tag
closes...EOL is good for single line tags, but what
if I have an author with a really long name or
something? Maybe we could use some kind of 'continue
on next line tag, like this:

/**
 * author: My author with a very long name must :-->
 * be continued on the next line.
**/

Or, how about mixing them?
Use the colon notation for single line tags, which
must end at the end of line, and use xml-style notation
if you need more than one line:

/**
 * author: OddesE
 * <author>My author with a very long name must
 * be continued on the next line.</author>
**/

With the very long contents of the second tag,
having to write a closing tag becomes less of a
burden. Plus, in practice allmost all tags are
one line, so generally you would have the
advantage of the colon notation.


--
Stijn
OddesE_XYZ@hotmail.com
http://OddesE.cjb.net
_________________________________________________
Remove _XYZ from my address when replying by mail

> something? Maybe we could use some kind of 'continue
> on next line tag, like this:
>
> /**
>  * author: My author with a very long name must :-->
>  * be continued on the next line.
> **/

If line continuation must be known then I'd propose _ like VB uses. But I don't think it's nessary.

> Or, how about mixing them?
> Use the colon notation for single line tags, which
> must end at the end of line, and use xml-style notation
> if you need more than one line:
>
> /**
>  * author: OddesE
>  * <author>My author with a very long name must
>  * be continued on the next line.</author>
> **/

I thought of that also but tossed out the idea. A return is simple enough to determine a new line.

> /**
>  * author: OddesE
>  * author: My author with a very long name must
>  * be continued on the next line.
> **/

The end of a tag definition can be found at either the start of the next tag or the end of the comment.

>
> With the very long contents of the second tag,
> having to write a closing tag becomes less of a
> burden. Plus, in practice allmost all tags are
> one line, so generally you would have the
> advantage of the colon notation.
>

I'd also propose that </> be used to indicate end of line (If it must be known). But I don't think this is necessary.

And if you want to use XML code still.

/**
 * author: OddesE
 * <author>My author with a very long name must
 * be continued on the next line.</>
**/

But that's still worse then.

/**
 * author: OddesE
 * author: My author with a very long name must
 * be continued on the next line.
**/

Even javaDoc did that.

It should be noted that XML is used for hierarchical data. ie <B><I></I></B> and this documentation form doesn't need that.

Hi all,

    	Some comments :

"anderson" <anderson@firestar.com.au> wrote in news:ah41br$1dih$1@digitaldaemon.com:

> 
> I thought of that also but tossed out the idea. A return is simple enough to determine a new line.
> 
>> /**
>>  * author: OddesE
>>  * author: My author with a very long name must
>>  * be continued on the next line.
>> **/
> 
> The end of a tag definition can be found at either the start of the next tag or the end of the comment.
> 
>>
>> With the very long contents of the second tag,
>> having to write a closing tag becomes less of a
>> burden. Plus, in practice allmost all tags are
>> one line, so generally you would have the
>> advantage of the colon notation.
>>

    	I think exists a regular expression, commonly used in lex, for
lexing the format. If one regexp could be found then the sintax is not
ambiguos. Please correct if I am wrong.

STARTDOC = '/**'['*']*\b
ENDDOC = ['*']'**/'
SINLINEDOC = '//*'\b
IDENTATION = [\b\t]*'*'\b
TAG = [a-z][a-z]*':'
TEXT = .

    	Someone could correct this ?

"anderson" <anderson@firestar.com.au> wrote in news:ah2u5e$5or$1@digitaldaemon.com:

> Source code documentation with coddocHow about a "requires" tag. Requirements could be auto generated but the doc program, but sometimes users may wish to add more details. I find it useful to quickly findout what is needed for a class without having to read through the sentenced documentation.
> 
> requires: STL, opengl.d
> 

How this differs from having code in "import" statement ?

Hi all,

    	I have thinked in tag like "glossary" and "category" for generating
indexes of hierarquical structures following different subjects.
    	It's possible generate indexes for each type of statement, classes,
modules, functions, contants.
    	This appear to be sufficient IMHO. What do you think?

"Robert M. Münch" <robert.muench@robertmuench.de> wrote in news:ah345k$c5o$1@digitaldaemon.com:

> "anderson" <anderson@firestar.com.au> schrieb im Newsbeitrag news:ah1mdt$1ugv$1@digitaldaemon.com...
> 
>> I know you've looked into Javadoc and Doxygen, but they also remove all
> the
>> code body parts which your app doesn't do.
> 
> Hi, my app doesn't do anything at the moment. I'm just thinking loud... It's no problem to just keep the header stuff. But sometimes it even makes sense to comment/explain your body. So both things should be supported very easy.
> 
>> In most documentation cases it is
>> important to hide the body and only show the header stuff. This means
>> that the hierarchical structures / summary and index files are the
>> most
> important
>> aspects of the doc generation program.
> 
> As said, these are just summaries of all the information collected while generating the output. So there is no problem to generate all kind of summaries in different level of detail. The question I find most interesting is how can we write code comfortable and add documentation where it needs to be. What kind of syntax should be used, what features are needed, what's the best usage pattern... etc. Of course it's a question of style but I don't like hughe comment boxes and special comment characters sequences to indicate what I want the output to look like. Of couse markup is needed but it should be as userfriendly as possible.
> 
> --
> Robert M. Münch

Juarez Rudsatz <juarez@nowhere.com> wrote in news:Xns924D92B1EB48Djuarezcorreiocom@63.105.9.61:

>          The problem is (3) yet. I don't sure syntax proposed is
>          non-ambiguos
> or easy to parse. But the problems must be stripped or remodeled. For
> example, the tag parameters in the proposed syntax are ugly.
> 

    	I have seen the form is used in mail specification for parameters:

MIME-version: 1.0
MIME-encoding: 7 bit

    	Enabling this "subtags" could be a good form of dealing with
parameters for comments ? What do you think ? There are another good way ?

E.g.:

/**
 * copyright: Pavel "EvilOne" Minayev
 * copyright-date: 2001
 * license : GPL
 * license-site : http://www.gnu.org/copyleft/gpl.html
 * version : 2.95.0.3
 * version-status : stable
 * bug : Windows 9x does not pass the correct memory used
 * bug-severity : low
 **/

"Juarez Rudsatz" <juarez@nowhere.com> wrote in message news:Xns924E82C49F90juarezcorreiocom@63.105.9.61...
> "anderson" <anderson@firestar.com.au> wrote in news:ah2u5e$5or$1@digitaldaemon.com:
>
> > Source code documentation with coddocHow about a "requires" tag. Requirements could be auto generated but the doc program, but sometimes users may wish to add more details. I find it useful to quickly findout what is needed for a class without having to read through the sentenced documentation.
> >
> > requires: STL, opengl.d
> >
>
> How this differs from having code in "import" statement ?

Sorry I was tring to indicate that the program should pick up things in the import statement, but if they were entered by the user the the program would add them if they didn't exist (the user may be planning to add it later).

Here's a more valid example,

requires: A fast 3d card, opengl multi-texturing extention, Index.dba, texture.bmp

These are things that can't be picked up by the doc generator but should be added in the same area include ones are does. Note that this should also be avaliable per-function as well.

"Juarez Rudsatz" <juarez@nowhere.com> wrote in message news:Xns924E86EA83162juarezcorreiocom@63.105.9.61...
> Juarez Rudsatz <juarez@nowhere.com> wrote in news:Xns924D92B1EB48Djuarezcorreiocom@63.105.9.61:
> 
> >          The problem is (3) yet. I don't sure syntax proposed is
> >          non-ambiguos
> > or easy to parse. But the problems must be stripped or remodeled. For
> > example, the tag parameters in the proposed syntax are ugly.
> > 
> 
>     I have seen the form is used in mail specification for parameters:
> 
> MIME-version: 1.0
> MIME-encoding: 7 bit
> 
>     Enabling this "subtags" could be a good form of dealing with
> parameters for comments ? What do you think ? There are another good way ?
> 
> E.g.:
> 
> /**
>  * copyright: Pavel "EvilOne" Minayev
>  * copyright-date: 2001
>  * license : GPL
>  * license-site : http://www.gnu.org/copyleft/gpl.html
>  * version : 2.95.0.3
>  * version-status : stable
>  * bug : Windows 9x does not pass the correct memory used
>  * bug-severity : low
>  **/

Looks good, although I don't know how often I'd use it. It'd be good for project programming. I guess if its there... I'd be nice if there was some central base for bug produced by the gen (perhaps optional). This way you could quickly find bugs to attempt to fix.

How about,

* bug-fixed : Windows 9x does not pass the correct memory used

for fixed bugs (simply add the -fixed to bug)
Also bugs should have optional titles as it makes things easier to fix if bugs have long definitions.

* bug-name : Win9x memory error

And also how about a company logo that will be placed on every page (next to copy write)

* logo : logo.gif

And a

* Updated : 2002.10.10

Although that could be determined though the file's attributes by default for the class; file dates are not always a correct indication of an update and not every method in a class will be updated every time.


--------------------------------------------------------------------------------


On another note

I'd think it would be also be nice to have the gen program produce html documents from a html templates. Of corse there would be a default one that comes with the program that you could customise.

You'd probably have these templates:

Index.htm - Frame based page
SideBar.htm - Hierarchical side bar
Class.htm - Class layout template
Method.htm - Methods layout
Property.htm - Property layout

Of course more though needs to be put into that.

Basically the generation program would copy the files as needed and look for special tags in the files to replace with code from the files. A bit of though will have to go into how list will be produced. Perhaps an XML derivative (without need for closing except on lists) could be used as tags in the html template files.

For example
(Although I don't like the extra typyness of xml it could be used for lists.)

...Sample html template code for Class...

//Other html code...

[CLASS]
<H1>[CLASS NAME]</H1>
Version : <B>[CLASS VERSION]</B>

[METHOD LIST]

<H2>[METHOD NAME/]</H2>
[COMMENT/]
<I>[AUTHOR/]</I>
<TAB>Version: <B>[VERSION/]</B></TAB>
[/METHOD LIST]

[/CLASS]

//Other html code...

The gen would search for the square brackets (I don't care what is used, except <> will be confided with html) and replace them with actual comments.

This way pages could be enhanced for the particular operation. I know it's good to have a common standard, but what if - say a company want to make all the pages in the same style as there webpage. It would be far easier to do this with template html. Also this would mean the layout of the gen could be improved over time. If I had time (an I don't) I'd program this myself in D as it doesn't look like a very tough job (but I could be wrong).

Yes interesting point.

You could write a book on D IDE's before they even come out. More then most languages I think that D would greatly from having it's own IDE. D code would become much neater on the web then other code more efficiently produced. I wouldn't be surprised if the D IDE had "an upload to web button" included (just kidding).  I suppose D could probably go a lot further (without abandoning the humble text editor) in supporting the IDE of the future, but I can't think of it how.

At the moment were stuck with 1990 style IDE's, with a language that was made for much classier IDE's. Most languages were born in the days of text editors, so they never though about support for IDE's. Instead the IDE's supported them.  Newer languages such as VB, Java and C# do have a lot of support IDE's. Those language (with exception of Java) I wouldn't dare attempt without the supporting IDE. D supports the best of both worlds although there's no real GUI object language (like VB and C# support) for it which is a downer. Besides D is in it's alpha stage so a GUI object language is long off I suppose.

"Sean L. Palmer" <seanpalmer@earthlink.net> wrote in message news:ah371f$h3i$1@digitaldaemon.com...
> I'd prefer the boxes to be done with HTML frames instead of ascii art.
>
> Actual source code could go into <CODE> <D> for (int i=0; i<100; ++i) {
> printf("D rocks!"); }</D> </CODE> blocks.  Which of course the editor
> wouldn't show you.
>
> Sean