www.digitalmars.com         C & C++   DMDScript  

D - Documentation Standard

reply Benji Smith <dlanguage xxagg.com> writes:
I was telling my younger brother, who is also a programmer, about the work I'm
doing to get the d repositiory website up and running, and the one thing that he
mentioned that he thought would be really important to making the project a
success was a documentation standard.

He talked about what a sucess CPAN is for the perl community, and how important
the perldoc format is to that success.

And then we both talked about the javadoc format and how we both really really
like to have a good set of javadocs handy whenever we're programming in Java.

And I've always been really annoyed at the lack of a consistent documentation
standard for C++ code.

So I think he made a very good point. We need a documentation standard.
Preferably, we need something like perldoc or javadoc that can automatically
build documentation from the sources in a project. And, what we really really
need is a tool that understands d code well enough to create library
documentation. We need something that can understand that a properly-formatted
comment attached to a delegate is not the same as the same comment attached to a
method or a class definition.

And, yes, we can use javadoc (or a number of other tools) right now, and they'll
do a reasonable job of associating comments with most coding constructs, but
ultimately we need our own documentation building tool. And we need to
standardize on using it for all of our projects, especially in our library
projects (which will probably be the dominant project type, for a little while
at least).

What do you think?

Is someone willing to take on this project?

--Benji Smith
Aug 29 2003
next sibling parent reply Benji Smith <dlanguage xxagg.com> writes:
Oh, and by the way, please don't talk to me about the "Embedding D in
HTML" (described here: http://www.digitalmars.com/d/html.html ).

I don't think I've ever seen a methodology that combined documentation
with obfuscation quite so well (if you're looking at the HTML/D
sources, that is).
Aug 29 2003
next sibling parent reply "Philippe Mori" <philippe_mori hotmail.com> writes:
"Benji Smith" <dlanguage xxagg.com> a écrit dans le message de
news:jdvukvgu01phro2rptbqviho3ce557tgmr 4ax.com...

 Oh, and by the way, please don't talk to me about the "Embedding D in
 HTML" (described here: http://www.digitalmars.com/d/html.html ).

 I don't think I've ever seen a methodology that combined documentation
 with obfuscation quite so well (if you're looking at the HTML/D
 sources, that is).


OTOH, I think that embedded HTML is a good thing but we need the following:

- an editor that knows about it so that:
    a) formatting can be automated
    b) we can embed HTML stuff (like an image from the editor)
    c) we can display raw D code, HTML code or D code formatted

- we should have special tags for the edition (for ex. to remember
bookmarks,
breakpoint location, compiler settings, last editing position, warnings that
are
ignored (per line), depedencies analysis, run-time statistics (performance
analysis,....), edition that where done -- a few undo and last save,
possibility
to hide or expand section of code and comments and remember their states,
special codes for revision, author, last author, last modification date and
other similar things that a version control system gives) so that it would
be
possible to keep all those information in a file

- we should uses CSS (or similar) to control formatting and to allows to
control what is displayed.

- the possibility to generate different variations for version controls,
documentation, publishing that would strip out what we don't want to keep
or add extra TAGs for formatting purpose (or hyperlink or ...)

- We should uses another extension (maybe .dd) because we want them to
open in the D editor and not in the WEB browser by default and we also
want to differentiate them from pure D file

I believe that using kind of HTML or XML embedded in the source would
allows a lot of things to be done with the source code and the editor would
allows to control what we see and ensure that everything is kept in
synchronisation if we modify the file a lot... and this would ensure
persistence
of those setting when the file get copied or re-opened later....
Aug 29 2003
parent Benji Smith <dlanguage xxagg.com> writes:
In article <bio4r7$2lrb$1 digitaldaemon.com>, Philippe Mori says...

"Benji Smith" <dlanguage xxagg.com> a écrit dans le message de
news:jdvukvgu01phro2rptbqviho3ce557tgmr 4ax.com...

 Oh, and by the way, please don't talk to me about the "Embedding D in
 HTML" (described here: http://www.digitalmars.com/d/html.html ).

 I don't think I've ever seen a methodology that combined documentation
 with obfuscation quite so well (if you're looking at the HTML/D
 sources, that is).


OTOH, I think that embedded HTML is a good thing but we need the following:

- an editor that knows about it so that:
    a) formatting can be automated
    b) we can embed HTML stuff (like an image from the editor)
    c) we can display raw D code, HTML code or D code formatted

- we should have special tags for the edition (for ex. to remember
bookmarks,
breakpoint location, compiler settings, last editing position, warnings that
are
ignored (per line), depedencies analysis, run-time statistics (performance
analysis,....), edition that where done -- a few undo and last save,
possibility
to hide or expand section of code and comments and remember their states,
special codes for revision, author, last author, last modification date and
other similar things that a version control system gives) so that it would
be
possible to keep all those information in a file

- we should uses CSS (or similar) to control formatting and to allows to
control what is displayed.

- the possibility to generate different variations for version controls,
documentation, publishing that would strip out what we don't want to keep
or add extra TAGs for formatting purpose (or hyperlink or ...)

- We should uses another extension (maybe .dd) because we want them to
open in the D editor and not in the WEB browser by default and we also
want to differentiate them from pure D file

I believe that using kind of HTML or XML embedded in the source would
allows a lot of things to be done with the source code and the editor would
allows to control what we see and ensure that everything is kept in
synchronisation if we modify the file a lot... and this would ensure
persistence
of those setting when the file get copied or re-opened later....
Aug 29 2003
prev sibling next sibling parent reply John Boucher <John_member pathlink.com> writes:
In article <jdvukvgu01phro2rptbqviho3ce557tgmr 4ax.com>, Benji Smith says...

Oh, and by the way, please don't talk to me about the "Embedding D in
HTML" (described here: http://www.digitalmars.com/d/html.html ).

I don't think I've ever seen a methodology that combined documentation
with obfuscation quite so well (if you're looking at the HTML/D
sources, that is).


I totally agree, as I've already said.
Plus one should not be required to use the same editor that the original writer
used in order to read the code clearly. I use just a plain old text editor.
The language is the language, the code should not include non-language elements.
Aug 29 2003
parent reply "Matthew Wilson" <matthew stlsoft.org> writes:
 Plus one should not be required to use the same editor that the original


writer

 used in order to read the code clearly. I use just a plain old text


editor.

This has merit, but the counter argument is that browsers are ubiquitous,
and it is therefore exceedingly unlikely to not have access to something
that can show you the code in an eminently readable format


 The language is the language, the code should not include non-language


elements.




Well, its swings and roundabouts. I'm much happier _overall_ to write .NET

since when it comes to documentation in one its a breeze, and in the other
an utter, utter nightmare. (Have you tried getting the doco from a MC++
project into the MSDN format, e.g. using NDoc? Nasty!)

I instinctively rail against the idea of non-plain-text format source code,
but I can tell you that the hassles in making the doco for the few SynSoft D
components (http://synsoft.org/d.html) was enough to make me open to the
idea of HTML-D.

I have to shamefacedly admit to checking out very few of the other D libs
out there. Can anyone let me know whether they've also documented theirs,
give links to such docos, and comment on the experiences?

Matthew
Aug 29 2003
parent reply Benji Smith <dlanguage xxagg.com> writes:
In article <bioko7$c8l$1 digitaldaemon.com>, Matthew Wilson says...

This has merit, but the counter argument is that browsers are ubiquitous,
and it is therefore exceedingly unlikely to not have access to something
that can show you the code in an eminently readable format


The trouble with this argument is that browsers are only a _display_ tool, not
an editing tool. To edit html without seeing all the nasty bits, you have to
edit it through a WYSIWYG editor like Dreamweaver or FrontPage. I don't want to
use an HTML editor to edit code just so that my variable names are rendered in
red text.

I've seen a number of handy tools for php and perl that take source code as
input and output a prettied-up, color-coded html version of the source code.
People use these tools for posting their code into web tutorials and whatnot. I
personally think that's pretty cool.

I also think it's pretty cool to embed xml tags in certain types of comments,
for the purpose of generating api documentation. I think it's a lot more handy
to write a <doc> </doc> set of comments than it is to use /// (which can be hard
to spot) to use for auto-doc generation.

But I don't think it's handy to have a bunch of <font color="red"></font> tags
around my class declarations, just so that they'll look pretty in a browser.
That's not helpful documentation. That's crazy.
Aug 29 2003
next sibling parent reply "Matthew Wilson" <matthew stlsoft.org> writes:
Agree with all that. ;)

"Benji Smith" <dlanguage xxagg.com> wrote in message
news:bion60$gh2$1 digitaldaemon.com...

 In article <bioko7$c8l$1 digitaldaemon.com>, Matthew Wilson says...

This has merit, but the counter argument is that browsers are ubiquitous,
and it is therefore exceedingly unlikely to not have access to something
that can show you the code in an eminently readable format


 The trouble with this argument is that browsers are only a _display_ tool,


not

 an editing tool. To edit html without seeing all the nasty bits, you have


to

 edit it through a WYSIWYG editor like Dreamweaver or FrontPage. I don't


want to

 use an HTML editor to edit code just so that my variable names are


rendered in

 red text.

 I've seen a number of handy tools for php and perl that take source code


as

 input and output a prettied-up, color-coded html version of the source


code.

 People use these tools for posting their code into web tutorials and


whatnot. I

 personally think that's pretty cool.

 I also think it's pretty cool to embed xml tags in certain types of


comments,

 for the purpose of generating api documentation. I think it's a lot more


handy

 to write a <doc> </doc> set of comments than it is to use /// (which can


be hard

 to spot) to use for auto-doc generation.

 But I don't think it's handy to have a bunch of <font color="red"></font>


tags

 around my class declarations, just so that they'll look pretty in a


browser.

 That's not helpful documentation. That's crazy.
Aug 29 2003
parent John Boucher <John_member pathlink.com> writes:
Hear Hear!

In article <bionc5$gn3$1 digitaldaemon.com>, Matthew Wilson says...

Agree with all that. ;)

"Benji Smith" <dlanguage xxagg.com> wrote in message
news:bion60$gh2$1 digitaldaemon.com...

 In article <bioko7$c8l$1 digitaldaemon.com>, Matthew Wilson says...

This has merit, but the counter argument is that browsers are ubiquitous,
and it is therefore exceedingly unlikely to not have access to something
that can show you the code in an eminently readable format


 The trouble with this argument is that browsers are only a _display_ tool,


not

 an editing tool. To edit html without seeing all the nasty bits, you have


to

 edit it through a WYSIWYG editor like Dreamweaver or FrontPage. I don't


want to

 use an HTML editor to edit code just so that my variable names are


rendered in

 red text.

 I've seen a number of handy tools for php and perl that take source code


as

 input and output a prettied-up, color-coded html version of the source


code.

 People use these tools for posting their code into web tutorials and


whatnot. I

 personally think that's pretty cool.

 I also think it's pretty cool to embed xml tags in certain types of


comments,

 for the purpose of generating api documentation. I think it's a lot more


handy

 to write a <doc> </doc> set of comments than it is to use /// (which can


be hard

 to spot) to use for auto-doc generation.

 But I don't think it's handy to have a bunch of <font color="red"></font>


tags

 around my class declarations, just so that they'll look pretty in a


browser.

 That's not helpful documentation. That's crazy.
Aug 29 2003
prev sibling parent reply "Philippe Mori" <philippe_mori hotmail.com> writes:
This has merit, but the counter argument is that browsers are ubiquitous,
and it is therefore exceedingly unlikely to not have access to something
that can show you the code in an eminently readable format




For sure, it is good if any browser could display the text readable but
by default, we may prefer not to have syntax highlighting in the code
so that it will be more readable in a text editor.


 The trouble with this argument is that browsers are only a _display_ tool,


not

 an editing tool. To edit html without seeing all the nasty bits, you have


to

 edit it through a WYSIWYG editor like Dreamweaver or FrontPage. I don't


want to

 use an HTML editor to edit code just so that my variable names are


rendered in

 red text.


So, all HTML tags should be optional...

OTOH, I think that it will be possible to make an editor that would allows
to edit D code without needing to display all the TAGs. Maybe a good editor
would allow the programmer to enter <doc> and automatically hide the TAG
and display the documentation in another color and add the closing TAG
automatically.

With time, I think we will have good editor for that and it will become the
norm to uses them...

I think that we could have tools that will add TAGs for syntax highlighting
when saving or exporting the file... and we should have the ability to strip
them if desired...


 I've seen a number of handy tools for php and perl that take source code


as

 input and output a prettied-up, color-coded html version of the source


code.

 People use these tools for posting their code into web tutorials and


whatnot. I

 personally think that's pretty cool.

 I also think it's pretty cool to embed xml tags in certain types of


comments,

 for the purpose of generating api documentation. I think it's a lot more


handy

 to write a <doc> </doc> set of comments than it is to use /// (which can


be hard

 to spot) to use for auto-doc generation.


And also, we need a way to tell the documentation tool what comments make
the doc... The tool should be able to extract other information from the
code
like function prototypes, preconditions, invariants,... and we should be
able to
add our own comments for the documentation to any declaration or statement.

And we might eventually have editor that would be able to automatically
embed
some TAGs that might be interesting for documentation purpose (like when
a function was last modified or a file...) Also, some information like the
revision
history could be between special TAG that the editor would now and allows to
display or hide easily...

A thing that might help ensure that the file is more or less readable in
text
is too allows to make reference to declarations that follows so that
documentation tools could uses it and the compiler could validate the
documentation (all parameters, all functions are documented).

An example:

<doc>
<doc decl=foo>This function does something.
<doc type=detail>Here we migh have more detailled description</doc>
</doc>
<doc decl=a> This parameter is the number of iteration to makes.
</doc>
void foo(int a)
{
    for (int i = 0; i != a; ++i)
    {
        <doc type=impl>Here we might have implementation doc</doc>
        // And we can have normal comments for code only documentation...
        do_something...
    }
}

Note that instead of type attribute, we mioght one to uses a style (CSS)
attribute so that it would be easy to apply different style to different
part
of the doc: We would have predefined classes for each kind of
supported documentation...

A documentation tool would then be able from the source to generate
much more usefull doc since the tool would know the purpose of
the comments (function prototype and parameters, function description,
function implementation notes,...)


 But I don't think it's handy to have a bunch of <font color="red"></font>


tags

 around my class declarations, just so that they'll look pretty in a


browser.

 That's not helpful documentation. That's crazy.


I also agree... A tool might add them from the source when we want to
display it
on the WEB. Ideally, a style sheet would be used so that we won't have one
file with keyword in red and another in blue,....

We should also be able to remove those syntax highlithing TAGs without
removing other TAGs like the ones for the documentation.
Aug 29 2003
parent Ilya Minkov <webmaster midiclub.de.vu> writes:
Philippe Mori wrote:


 A documentation tool would then be able from the source to generate
 much more usefull doc since the tool would know the purpose of
 the comments (function prototype and parameters, function description,
 function implementation notes,...)


Besides, D promotes a style of mixing interface and implementation. I'm 
not sure whether i approve the style by itself or not, but it definately 
takes some viewer/editor support. Like, Scintilla component used in 
modern IDEs can roll together parts which one need not usually see.

This basically boils down to excluding implementation from the 
documentation and making it available optionally. Besides, usually the 
documentation needn't be in exactly the same order as code, although D 
reliefs the constraints on code placement and thus this problem is less 
severe.

Another thing is that writing raw, simple code is much more pleasant 
than HTML or point-and-click, which is simply distracting. The ultimate 
experience of working with TeX, or any other simple and legible 
language. Something which we cannot have with HTML.

It is probably wise to define a snorkel-free documentation format, which 
would work well in raw text. Finally, i recall some people in this 
newsgroup use VIM only, and that for good reasons. Do they have to be 
"impaired" or "disabled" because of that?

-eye/midiclub
Aug 30 2003
prev sibling parent "Matthew Wilson" <matthew stlsoft.org> writes:
there was a recent article in DDJ (don't have ref to hand, sorry) that put a
compelling case for just this functionality in pretty much all future
(versions of) languages.

I think it's cool that the language supports it, but am not necessarily
convinced that it's the way forward.

I do think it's interesting enough that you don't just dismiss it as the
solution to your documentation problem.

"Benji Smith" <dlanguage xxagg.com> wrote in message
news:jdvukvgu01phro2rptbqviho3ce557tgmr 4ax.com...

 Oh, and by the way, please don't talk to me about the "Embedding D in
 HTML" (described here: http://www.digitalmars.com/d/html.html ).

 I don't think I've ever seen a methodology that combined documentation
 with obfuscation quite so well (if you're looking at the HTML/D
 sources, that is).
Aug 29 2003
prev sibling next sibling parent reply Brad Anderson <brad sankaty.com> writes:
Benji Smith wrote:


 He talked about what a sucess CPAN is for the perl community, and how important
 the perldoc format is to that success.
 
 And then we both talked about the javadoc format and how we both really really
 like to have a good set of javadocs handy whenever we're programming in Java.
 


So we need markers within the D source code itself:

/** like javadoc, but also /++ for D

and fields  author  compiler, etc.


 So I think he made a very good point. We need a documentation standard.
 Preferably, we need something like perldoc or javadoc that can automatically
 build documentation from the sources in a project. And, what we really really
 need is a tool that understands d code well enough to create library
 documentation. We need something that can understand that a properly-formatted
 comment attached to a delegate is not the same as the same comment attached to
a
 method or a class definition.
 


And we need a separate executable (DDoc Utility) that reads source of a 
project and creates HTML.  Am I tracking here?

I'm not sure if the DDoc utility is the proper place, but I would also 
like to have a source code formatter like Jalopy 
(http://jalopy.sourceforge.net/) that understood D code and reformatted 
it to a standard coding format agreed upon by an entire company (or for 
our libraries, an entire community).


 
 Is someone willing to take on this project?
 


My skills are heaviest in HTML/JS/CSS and Java/JSP.  I could contribute 
a lot to that part of the project.  I am attempting to learn D by first 
designing a source code formatter for JSP pages, and then attempting to 
make a D version of a servlet container (D Server Pages).  Those plans 
sound like I'm trying to swallow the entire elephant...

Some of the work on the source code formatter might be reused for the 
DDoc utility, or maybe I should try my hand at the DDoc utility first. 
Thoughts?

Would I be able to get assistance on parts of D code that I would need 
to understand, like differences from Java code?  I'm specifically 
looking at Javadoc and seeing Use or Tree sections that could get very 
hairy...  And I am at a novice/intermediate level in using C/C++/D type 
languages, but learn fast.

Brad
Aug 29 2003
parent "Matthew Wilson" <matthew stlsoft.org> writes:
 I'm not sure if the DDoc utility is the proper place, but I would also
 like to have a source code formatter like Jalopy
 (http://jalopy.sourceforge.net/) that understood D code and reformatted
 it to a standard coding format agreed upon by an entire company (or for
 our libraries, an entire community).


I wrote a COM-based plug-in tool a few years ago that allows me to change
bracing styles, or to insert JavaDoc section, in a recursive fashion (and
operated on projects of 100Ks of LOC in a couple of minutes), as well as
report on things such as unused imports, unused private variables, etc. etc.
It works with Java, and to some broken extent Perl. I've vague plans

long time away.

(Hmmm, I miss fiddling with all that stuff. May have to resurrect it .... ;)

I've actually thought about this wrt D a fair bit, and I really think that
probably the best way to do this would be for someone to work with Walter in
adapting the lexer/parser part of the compiler to work with such a tool,
with similar published plug-in Reporter/Transmuter interfaces, and then we
could all write whatever plug-ins we wanted. These could be reformatters, or
doc extraction, or even doc insertion!

Walter, does the current compiler architecture lend itself to this?
Aug 29 2003
prev sibling parent reply "Matthew Wilson" <matthew stlsoft.org> writes:
 And, yes, we can use javadoc (or a number of other tools) right now, and


they'll

 do a reasonable job of associating comments with most coding constructs,


but

 ultimately we need our own documentation building tool. And we need to
 standardize on using it for all of our projects, especially in our library
 projects (which will probably be the dominant project type, for a little


while

 at least).

 What do you think?


I think it'd be great, as long as its compatible with Doxygen *and* javadoc,
so that any libraries documented using either format does not have to be
upgraded until the poor overworked developer is able to do so.


 Is someone willing to take on this project?


Alas, not I. ;)
Aug 29 2003
parent "Ben Hinkle" <bhinkle4 juno.com> writes:
 I think it'd be great, as long as its compatible with Doxygen *and*


javadoc,

 so that any libraries documented using either format does not have to be
 upgraded until the poor overworked developer is able to do so.


I also vote for doxygen. It does wonders for C++. I hope it is flexible
enough to easily add new language support.
Aug 30 2003