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

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

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

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

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.
The C# use of /// is bad enough.

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

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

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

> 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.
> The C# use of /// is bad enough.

Well, its swings and roundabouts. I'm much happier _overall_ to write .NET components in C#, with semi-smart commenting, than MC++ which has none, 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

> 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 (whenever time may allow) to update it to handle C# and D, but it may be a 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?