Just have the documentation have hyperlinks to the appropriate section of the D file, and the D file has marker tags you can hyperlink to, one for each thingy such as class or function.  It'd also be nice for a member function to have a hyperlink to the class declaration, an import module directive to have a hyperlink to that module, etc.  In fact these could be generated automatically;  perhaps the compiler could insert them if requested to do so.

Sean

"Robert M. Münch" <robert.muench@robertmuench.de> wrote in message news:ah0ggd$niq$1@digitaldaemon.com...
> 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).

Perhaps, there could be automatic hierarchical generation in some docgen like program. I think something along these lines was mentioned before (except it was compiler based). The hierarchical generator would simply scan all the D html files and built a code map, possibly using a UML derivative.  It would also generate a framed index file. So I still see a need for tags.

  The program could reformat these tags and automatically add things like see. This would provide a way to have automatically generated comments in the code itself not just the html. Now if someone is using a text editor for D, this could make things messy so the html (or xhtml) would have to be kept neat in a text form as well. There could also be special tags to indicate not to do certain things.

      /**
       * <author>Micky mouse</author>
       * <version>1.0</version>
       *
       *  The does blah blah blah blah blah blah blah blah blah blah blah blah
      *   blah blah blah blah blah blah blah blah blah blah blah blah blah blah
      *   blah blah blah blah blah
      **/
void func(int a)
{
...
}

Would change to
  void func(int a)
      Parameters

      a : Unknown




      The does blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah

      Micky mouse

      See
             func2, func3





      V 1.0





      {

      ...
      }




Anyway that's just an idea of a possible layout (athough it'll need alot more work).  The docGen should reconise both formats so that it can reconise what it has generated. Also classes could be done in a UML style by dividing the varaibles from the functions.

"Robert M. Münch" <robert.muench@robertmuench.de> wrote in message news:ah0ggd$niq$1@digitaldaemon.com...
> 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).
> 
> 

Perhaps, there could be automatic hierarchical generation in some docgen like program. I think something along these lines was mentioned before (except it was compiler based). The hierarchical generator would simply scan all the D html files and built a code map, possibly using a UML derivative.  It would also generate a framed index file. So I still see a need for tags.

  The program could reformat these tags and automatically add things like see. This would provide a way to have automatically generated comments in the code itself not just the html. Now if someone is using a text editor for D, this could make things messy so the html (or xhtml) would have to be kept neat in a text form as well. There could also be special tags to indicate not to do certain things.

      /**
       * <author>Micky mouse</author>
       * <version>1.0</version>
       *
       *  The does blah blah blah blah blah blah blah blah blah blah blah blah
      *   blah blah blah blah blah blah blah blah blah blah blah blah blah blah
      *   blah blah blah blah blah
      **/
void func(int a)
{
...
}

Would change to
  void func(int a)
      Parameters

      a : Unknown




      The does blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah

      Micky mouse

      See
             func2, func3





      V 1.0





      {

      ...
      }




Anyway that's just an idea of a possible layout (athough it'll need alot more work).  The docGen should reconise both formats so that it can reconise what it has generated. Also classes could be done in a UML style by dividing the varaibles from the functions.

"Robert M. Münch" <robert.muench@robertmuench.de> wrote in message news:ah0ggd$niq$1@digitaldaemon.com...
> 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).
> 
> 

  "anderson" <anderson@firestar.com.au> wrote in message news:ah0pub$111p$1@digitaldaemon.com...
  Perhaps, there could be automatic hierarchical generation in some docgen like program. I think something along these lines was mentioned before (except it was compiler based). The hierarchical generator would simply scan all the D html files and built a code map, possibly using a UML derivative.  It would also generate a framed index file. So I still see a need for tags.

    The program could reformat these tags and automatically add things like see. This would provide a way to have automatically generated comments in the code itself not just the html. Now if someone is using a text editor for D, this could make things messy so the html (or xhtml) would have to be kept neat in a text form as well. There could also be special tags to indicate not to do certain things.

        /**
         * <author>Micky mouse</author>
         * <version>1.0</version>
         *
         *  The does blah blah blah blah blah blah blah blah blah blah blah blah
        *   blah blah blah blah blah blah blah blah blah blah blah blah blah blah
        *   blah blah blah blah blah
        **/
  void func(int a)
  {
  ...
  }

  Would change to
    void func(int a)
        Parameters

        a : Unknown




        The does blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah

        Micky mouse

        See
               func2, func3





        V 1.0





        {

        ...
        }




  Anyway that's just an idea of a possible layout (athough it'll need alot more work).  The docGen should reconise both formats so that it can reconise what it has generated. Also classes could be done in a UML style by dividing the varaibles from the functions.

  "Robert M. Münch" <robert.muench@robertmuench.de> wrote in message news:ah0ggd$niq$1@digitaldaemon.com...
  > 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).
  >
  >

Yes I definitely agree with this.
Putting the code in an .html file is a nice feature for demo programs
that get posted on web sites, but it doesn't work so well for pure
documentation. I don't know if the people that mentioned this have
tried javadoc or doxygen, but creating documentation from source code
and embedding source code in .html are just two completely different
things. I don't see myself typing all the .html to create fancy layout
like above when writing a .d program. Also Javadoc and Doxygen create
hierarchical structures of your classes, summary and index files,
links from one class to the others that are mentioned and to its
parents, etc, etc, etc. Am I supposed to do this all by hand?

Even if I was willing and capable of doing all this by hand, I could never benefit from other people using it to and all formats would be radically different.

Just search the web for Java documentation. Notice how it is all uniform and looks alike? This is because all this documentation is generated using Javadoc. The 'embed d code in a .html file' technique is not an option for documentation generation.


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

"Sean L. Palmer" <seanpalmer@earthlink.net> wrote in message news:agv4b1$2cb9$1@digitaldaemon.com...
> Some D people Just Don't Care that much about Standardized Documentation. I'm sure you guys will come up with something good.
>
> Sean
>



Have you ever used programs like DoxyGen or JavaDoc?
They rule! I have an assertion that says:
"If your public class or function is not documented,
it might as well be private."
It is a little rough, but think of the undocumented
Windows API functions, or undocumented Delphi classes
or functions, and it is (kinda :) true.

Good documentation helps code-reuse, and thus it
is important.

Tools like Javadoc have really helped, but Javadoc
is a standard tool in the Java SDK. If we as the
D community want such tools too, we have to find
someone crazy enough to build one. It would be cool
if it would be built to a standard that was reached
in concensus, instead of to the whims of whoever
was designing it at that point...

Fortunately Walter has made all the parsing code
open source and published it, so that should help
someone wanting to do an implementation.


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

Sorry must have been a brake down in my comunication. I think javaDoc is cool. The code segment should be left out, parhaps an optional line number instead. In a D IDE it'd be good to have a switch that turns automatic html formating that could be toggled on and off that would do formating simular to the javaDoc (but with code segs).
  "OddesE" <OddesE_XYZ@hotmail.com> wrote in message news:ah19po$1hh9$1@digitaldaemon.com...
    "anderson" <anderson@firestar.com.au> wrote in message news:ah0pub$111p$1@digitaldaemon.com...
    Perhaps, there could be automatic hierarchical generation in some docgen like program. I think something along these lines was mentioned before (except it was compiler based). The hierarchical generator would simply scan all the D html files and built a code map, possibly using a UML derivative.  It would also generate a framed index file. So I still see a need for tags.

      The program could reformat these tags and automatically add things like see. This would provide a way to have automatically generated comments in the code itself not just the html. Now if someone is using a text editor for D, this could make things messy so the html (or xhtml) would have to be kept neat in a text form as well. There could also be special tags to indicate not to do certain things.

          /**
           * <author>Micky mouse</author>
           * <version>1.0</version>
           *
           *  The does blah blah blah blah blah blah blah blah blah blah blah blah
          *   blah blah blah blah blah blah blah blah blah blah blah blah blah blah
          *   blah blah blah blah blah
          **/
    void func(int a)
    {
    ...
    }

    Would change to
      void func(int a)
          Parameters

          a : Unknown




          The does blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah

          Micky mouse

          See
                 func2, func3





          V 1.0





          {

          ...
          }




    Anyway that's just an idea of a possible layout (athough it'll need alot more work).  The docGen should reconise both formats so that it can reconise what it has generated. Also classes could be done in a UML style by dividing the varaibles from the functions.

    "Robert M. Münch" <robert.muench@robertmuench.de> wrote in message news:ah0ggd$niq$1@digitaldaemon.com...
    > 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).
    >
    >

  Yes I definitely agree with this.
  Putting the code in an .html file is a nice feature for demo programs
  that get posted on web sites, but it doesn't work so well for pure
  documentation. I don't know if the people that mentioned this have
  tried javadoc or doxygen, but creating documentation from source code
  and embedding source code in .html are just two completely different
  things. I don't see myself typing all the .html to create fancy layout
  like above when writing a .d program. Also Javadoc and Doxygen create
  hierarchical structures of your classes, summary and index files,
  links from one class to the others that are mentioned and to its
  parents, etc, etc, etc. Am I supposed to do this all by hand?

  Even if I was willing and capable of doing all this by hand, I could
  never benefit from other people using it to and all formats would be
  radically different.

  Just search the web for Java documentation. Notice how it is all
  uniform and looks alike? This is because all this documentation is
  generated using Javadoc. The 'embed d code in a .html file' technique
  is not an option for documentation generation.


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

On Tue, 16 Jul 2002 09:08:15 +0200, "Robert M. Münch" <robert.muench@robertmuench.de> wrote:
> 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
> 
> 

Hmm.. Maybe it's time we thought in terms of coding our documentation rather than documenting our code.

"OddesE" <OddesE_XYZ@hotmail.com> schrieb im Newsbeitrag news:ah19po$1hh9$1@digitaldaemon.com....

>tried javadoc or doxygen, but creating documentation from source code and embedding source code in .html are just two completely different things. I don't see myself typing all the .html to create fancy layout like above when writing a .d program.

Hi, you don't have to that's what the generator will do for you.

>Also Javadoc and Doxygen create
>hierarchical structures of your classes, summary and index files,
>links from one class to the others that are mentioned and to its
>parents, etc, etc, etc. Am I supposed to do this all by hand?

No, but these are just some special sections/summaries/references the generator can include.

>Just search the web for Java documentation. Notice how it is all uniform and looks alike? This is because all this documentation is generated using Javadoc. The 'embed d code in a .html file' technique is not an option for documentation generation.

Well, the literate programming people will say something different. Here is a short example of how such a file could look like:

===Introduction
Bla bla

---Colors
Colors for syntax highlighting, default values are my preferences in Microsoft Visual Studio editor

    class Colors
    {
     static char[] keyword = "0000FF";
     static char[] number = "008000";
     static char[] string = "000080";
     static char[] comment = "808080";
    }

etc.

The indented code will be compileable by D the rest will be used to generate HTML output. That's easy! Adding all kinf of special source-code documentation features shouldn't be a problem. Robert

I wanna discuss the proposal about xml:

<quoted from="post" author="OddesE" day="dom">

As you will see in the next section I propose a change in the standard that is pretty big. I say we change the way tags are described to a method that is essentially xml compliant. There are a few reasons for this:

- xml is a standard. ;)
- xml has been well thought out and will most likely be more easy to write
a parser for, but better still, we probably don't even have to do this,
because we can use an existing parser.
xml is well known so people will probably understand it easier.
- This way we don't have to differentiate between single-line and multi-
line tags.
- You can write a dtd or schema which states the rules for comments in a
machine readable way, so checking if the code is ok could be automatic.
- You can write an xslt stylesheet for translating the xml code to other
document formats.
- The code to parse xml, check it's syntax using schema's or dtd's and
transforming it into other documents using stylesheets has already been
written, and is available, for free, on almost any platform and in almost
any language. This would greatly simplify the creation of a DDoc
application.

</quoted>


Basically the reasons for adopting xml as commenting are:

- xml is standart and well known
- The syntax is strong
- Could be easy write a program to parse comments with xml
- You can use already coded programs to simplify generation of programs

    	I have thinked about using xml. But IMHO xml don't satisfy all
objectives of a documentation tool.
    	Some of objectives for me are:

1 - Programmer must do the minimal effort possible
2 - The documentation in source code must be clear
3 - Syntax must be strong and non ambigous
4 - Syntax must be flexible enough for the tools generate many formats as
possible

I have looked in documentation of some tools, like Javadoc, doxygen and so on. My motivation for using the format proposed is :

* author: name
* <author>name</author>
* @author: name

    	The first is more intuitiv, clear and easy to write. The tools can
easily parse documents like this and couldn't be so hard to write a lexer
or a parse for this.
    	The xml form is not so clear as the first and adds unnecessary
garbage, the closing tag. Once the comments can have a visual effect
newlines can be used for end-of-element parsing. I think using xml we pass
to programmer the work what must be of compiler. So IMHO the xml fails in
(1) and (2).
    	All good points for xml came from it can satisfy (3) and (4).
    	For (4) I have thinked in a simple solution : decouple the document
generation from document parsing. The tool must not generate a final
document. Is best, for example, generate a xml docbook and than apply a new
tool for generating the document, jade, xlst, etc... But this is work for a
compiler ( for human knowledge to general programming format like xml ).
    	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 think this is the first point to discuss and define. And maturing a
little bit more could be good.
    	The all post until now have been good and showed anothers
perspectives for the documentation. Let's continue...

Juarez Rudsatz

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

> Well, the literate programming people will say something different. Here
is
> a short example of how such a file could look like:
>
> ===Introduction
> Bla bla
>
> ---Colors
> Colors for syntax highlighting, default values are my preferences in Microsoft Visual Studio editor
>
>     class Colors
>     {
>      static char[] keyword = "0000FF";
>      static char[] number = "008000";
>      static char[] string = "000080";
>      static char[] comment = "808080";
>     }
>
> etc.
>
> The indented code will be compileable by D the rest will be used to
generate
> HTML output. That's easy! Adding all kinf of special source-code documentation features shouldn't be a problem. Robert

I know you've looked into Javadoc and Doxygen, but they also remove all the code body parts which your app doesn't do. 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.