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