[svanleent]

Looked at Doxygen and other documentation tools, none of them have good support for D. Templates, modulair design, contracts, automatic properties/method conversion, delegates all those little bits which are so important to D.

The idea behind DDoc is to make a tool with modern standards such as XML which translates D source files into proper source/API documentation. DDoc would support filters, not only to generate XHTML files but also to be able to put documentation into searchable databases (which can be searched online, for large projects) and for internal use in for example IDE's and into other environments using filters.

I would like to start DDoc as project, if there are questions about it, don't hesitate to ask.
_________________
How C++ became ancient

[larsivi]

I voted for Qt as I think that would mean Doxygen-like. Anyway, I contemplated a similar tool recently for just the same reasons. I also thought of an intermediate format (most likely to be XML), especially as it would help generate different documentation formats, but also to help facilitate support for more languages than just D. The tool was supposed to be called DocumenteD, btw. Since it's a great name, you should steal it. I dropped it, probably because I wanted it to be very easy to extend, ironically making a complex solution.

[svanleent]

[HelmutLeitner]

I think DDoc is a good name.

It would be nice to go for a synergy: to make a great tool for documenting D and ... to show that D is a great language for such a tool (this will only work if DDoc is built as a replacement and extension for some existing tool so that users can switch easily and see the difference in reduced codesize and increased performance and flexibility).

I know nothing about the typical structure of these tools, but I would assume that they use a front end (language, e. g. D, Java) - intermediate database - back end (output, e.g. HTML, PDF) architecture. If this is the case, I would vote to potentially support multiple syntaxes in the front end and XML in the intermediate database.

--
Helmut

[svanleent]

I have a minimal design of how the system should work. However, I can't get it online at the moment. However, if someone want's to have the design, please don't hesitate to contact me.
_________________
How C++ became ancient

[smjg]

My thought is for a three-layer process.

Front-end: to parse the code and comments, and produce a suitable internal representation of the code structure and comments. Maybe we could take and adapt the DMD front end to do this. Ongoing maintenance would be to keep up with D, or if we're eventually going to support other languages as well, we'd create more front-ends.

Middle-end: to analyse the documentation comments, and generate documentation in some internal structured form. Ongoing maintenance would be to support more documentation features.

Back-end: to generate HTML, RTF, LaTeX or whatever from the internal form. Different back-ends would implement different document formats, or maybe different documentation layouts beyond what CSS and the like can do.

Of course, the internal database (filled in by both the front-end and the middle-end) would perhaps be a fourth layer, forming the link between the other three. Ideally it should be designed with forward and backward compatibility in mind.

I've kind of grown into the Qt style after using Doxygen for a while. Maybe we should take this and work out how to improve on it.

Stewart.

[svanleent]

I think most people agree that it should be a three-layered system. I think in the idea of open source that we should take OpenD and use it as base for building the documentation system.
_________________
How C++ became ancient

[svanleent]

As I'm just reading the poll, it seems most people like the Qt syntax. So I would say let's use it.

Some problems that may occur are:

- template parameters
- class template parameters
- invariant blocks
- unittest blocks
- alias and typedef items
- class vs. module
- and perhaps even more

So if anyone wants to volunteer to create some nice Qt-styled parameters for this I would be very happy about it.

Perhaps we should use the OpenD lexer/parser to read out the file. Another manner would be to implement a reverse-scanner algorithm (from bottom to top), which also could detect most important semantic and syntactical properties of a typical D file.
_________________
How C++ became ancient

[Hohums]

Doxygen like. Its the most advanced (I know of). It's also supports javadoc like at Qt like. Its all in one really.
_________________
http://badmama.com.au/~anderson/

[svanleent]

Since most people are used to use Qt-style, we should first concentrate on that. After we get something decent working, we can go concentrating on other aspects such as supporting Javadoc
_________________
How C++ became ancient

[BenHinkle]

how do I vote? I'll just post my vote. I prefer JavaDoc style over Qt though supporting both would be great.

[BenHinkle]

[svanleent]

Currently the best way to go is (I think) to implement a QT style implementation. If this is working, we can create Javadoc and XML style implementations.

Something as the following could be implemented:

/*!
* \brief Short Description
*
* Description
*
* \arg[a,in] Parameter Description
* \arg[b,out] Parameter Description
* \return Return Description
*/
int foo(in int a, out int b) {
b = a * 2;
return a ^ 2;
}
_________________
How C++ became ancient

[kris]

[svanleent]

I don't see any problem in making this feature pluggable. the only thing which must be adapted is the scanner algorithm. The whole application is going to be pluggable, as I want to introduce the possibility to extract comments out of for example DSP pages as well.

This means:

making DSO's/DLL's out of scanners

--- or ---

making a script engine wherein a scanner algorithm can be defined
_________________
How C++ became ancient