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