I am sending a very preliminary version of a specification for
implementing a sintax for document source files using the /* */ comments.
    	It's a preliminary version and contain, certainly, design and
language errors.
    	Please read the attached html file and send your comments.

Juarez Rudsatz

Source code documentation with coddocThis is very complete and I can't think of much to add.

Is it possible to have html links in documentation, or better yet html code? I know "see" has this ablity, but what about in a general comment. For example In some cases you may want to insert a picture of what your talking about.

Source code documentation with coddocI read the document, and I think it is
a very good initiative.
We definitely need some kind of standard for this, or we will
end up with a whole bunch of similar standards that differ in
just enough respect to be a pain in the you-know-where.

I do propose one big and a whole bunch of small alterations to the standard. I have marked sections that I have added in green, comments in red and sections that I think should be deleted in gray.

The text that still is black also had changes in them, but these are just small things such as corrected spelling errors, they don't change the standard in any way.

The modified file is attached.


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

Source code documentation with coddoc"anderson" <anderson@firestar.com.au> wrote in message news:agoaa2$16a9 $1@digitaldaemon.com...
> This is very complete and I can't think of much to add.
>
> Is it possible to have html links in documentation,
> or better yet html code?
> I know "see" has this ablity, but what about in a general
> comment. For example In some cases you may want to insert
> a picture of what your talking about.


I agree, this is a very useful feature, and most
tools support this.


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

Some good points. I like the XML (although it'll mean more typing). What will happen if the D file is saved as a html? You'd have to do a bit of stuffing I supose. Parhaps that should be in the documentation.
  "OddesE" <OddesE_XYZ@hotmail.com> wrote in message news:agt6me$9ht$1@digitaldaemon.com...
  Source code documentation with coddocI read the document, and I think it is
  a very good initiative.
  We definitely need some kind of standard for this, or we will
  end up with a whole bunch of similar standards that differ in
  just enough respect to be a pain in the you-know-where.

  I do propose one big and a whole bunch of small alterations
  to the standard. I have marked sections that I have added in
  green, comments in red and sections that I think should be
  deleted in gray.

  The text that still is black also had changes in them, but
  these are just small things such as corrected spelling
  errors, they don't change the standard in any way.

  The modified file is attached.


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

"OddesE" <OddesE_XYZ@hotmail.com> schrieb im Newsbeitrag news:agt6tf$9to$1@digitaldaemon.com...

> I agree, this is a very useful feature, and most
> tools support this.

Hi, if you want to write TXT in a very easy manner and get good looking HTML out of  it have a look at my make-doc-pro on my homepage. This is a Rebol script and you will find some getting-started infos too. My homepage has been done with this tool.

If you have any questions let me know.

--
Robert M. Münch
IT & Management Freelancer
Mobile: +49 (0)177 2452 802
Fax   : +49 (0)721 8408 9112
Web   : http://www.robertmuench.de

Hi,

    	I busy right now. I will read carefuly all posts and reply late. I
think the initiative must not be closed. And many "D" people should
contribute.

"OddesE" <OddesE_XYZ@hotmail.com> wrote in news:agt6me$9ht$1@digitaldaemon.com:

> Source code documentation with coddocI read the document, and I think
> it is a very good initiative.
> We definitely need some kind of standard for this, or we will
> end up with a whole bunch of similar standards that differ in
> just enough respect to be a pain in the you-know-where.
> 
> I do propose one big and a whole bunch of small alterations to the standard. I have marked sections that I have added in green, comments in red and sections that I think should be deleted in gray.
> 
> The text that still is black also had changes in them, but these are just small things such as corrected spelling errors, they don't change the standard in any way.
> 
> The modified file is attached.
> 
> --
> Stijn
> OddesE_XYZ@hotmail.com
> http://OddesE.cjb.net
> _________________________________________________

Some D people Just Don't Care that much about Standardized Documentation. I'm sure you guys will come up with something good.

Sean

"Juarez Rudsatz" <juarez@nowhere.com> wrote in message news:Xns924C7EB89CDB6juarezcom@63.105.9.61...
>     I busy right now. I will read carefuly all posts and reply late. I
> think the initiative must not be closed. And many "D" people should
> contribute.

Source code documentation with coddocThis is more of a doc generation suggestion.  I think it would be good if of doc generator had some infromation about the line number where the code begins. This would help enable furture IDE's to use the documentation as a basics for the IDE layout.

I know I've said this before, but It would be cool if the docgen could produce code in an uml format.

PS - Robert M. Münch tool produces quite nice output, and I'd recommend it for this "Code documentation attachement". Also it mite be an idea for the D Journal if documents are to be produced to some standard (although it may mean extra reformating work). It handles code segments especially well (by picking up tabs).

Source code documentation with coddocHi, thanks a lot. There is something that comes to mind: D can compile HTML files! So it maybe best to include D code into the documentation and not documentation into D code. My script could easly be changed to produce a compileable output file. With this we would be able to move more into the WEB idea of litteral programming. Code is already recognized as mentioned. What do you think? Robert


"anderson" <anderson@firestar.com.au> schrieb im Newsbeitrag
news:ah0fv5$m3f$1@digitaldaemon.com...
PS - Robert M. Münch tool produces quite nice output, and I'd recommend it
for this "Code documentation attachement". Also it mite be an idea for the D
Journal if documents are to be produced to some standard (although it may
mean extra reformating work). It handles code segments especially well (by
picking up tabs).