View previous topic :: View next topic |
DDoc should use ... syntax in source files |
Javadoc |
|
14% |
[ 2 ] |
Qt |
|
42% |
[ 6 ] |
XML-like |
|
35% |
[ 5 ] |
Other |
|
7% |
[ 1 ] |
|
Total Votes : 14 |
|
Author |
Message |
svanleent
Joined: 25 Sep 2004 Posts: 53
|
Posted: Sat Sep 25, 2004 8:44 am Post subject: DDoc Documentation Generation for D |
|
|
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 |
|
Back to top |
|
![](templates/subSilver/images/spacer.gif) |
larsivi Site Admin
Joined: 27 Mar 2004 Posts: 453 Location: Trondheim, Norway
|
Posted: Sat Sep 25, 2004 2:30 pm Post subject: |
|
|
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. |
|
Back to top |
|
![](templates/subSilver/images/spacer.gif) |
svanleent
Joined: 25 Sep 2004 Posts: 53
|
Posted: Sat Sep 25, 2004 3:14 pm Post subject: |
|
|
Quote: | I voted for Qt as I think that would mean Doxygen-like... |
To be honest with you, I use Javadoc style, but the differences of the two (except the syntax) are not that different. XML syntax on the other hand offers a wider way to define things (but makes it possibly harder to maintain).
I'll go with Qt-style (Same as Doxygen) or Javadoc-style but for many typically D-things there are no names, perhaps someone would like to invent some new tags to use within the documentation.
Quote: | ... 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... |
Well, the problem of D is that it is so good. Simply said, D offers so much (mixins, aliases, highly sophisticated template design, OO) that the current tools are simply not sufficient enough. Meaning in other words, it needs a new tool.
Quote: | The tool was supposed to be called DocumenteD, btw. Since it's a great name, you should steal it... |
Will surely be considered in the final name poll or debate!
Quote: | ...I dropped it, probably because I wanted it to be very easy to extend, ironically making a complex solution |
What can I say, we're not in a perfect world . The solution I'm thinking about is extendable in one direction, towards the documentation format. Normally, only D source files (and in future also DSP and so forth) will be taken by the parser, but it shouldn't take C/C++ files etcetera. This does not mean that there must be no collaboration with other tools (such as Doxygen), it should do to offer a wider spread documentation tooling base. _________________ How C++ became ancient |
|
Back to top |
|
![](templates/subSilver/images/spacer.gif) |
HelmutLeitner
Joined: 28 May 2004 Posts: 5 Location: Graz, Austria
|
Posted: Tue Sep 28, 2004 1:44 am Post subject: |
|
|
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 |
|
Back to top |
|
![](templates/subSilver/images/spacer.gif) |
svanleent
Joined: 25 Sep 2004 Posts: 53
|
Posted: Tue Sep 28, 2004 3:29 am Post subject: |
|
|
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 |
|
Back to top |
|
![](templates/subSilver/images/spacer.gif) |
smjg
Joined: 29 Sep 2004 Posts: 41
|
Posted: Wed Sep 29, 2004 11:59 am Post subject: |
|
|
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. |
|
Back to top |
|
![](templates/subSilver/images/spacer.gif) |
svanleent
Joined: 25 Sep 2004 Posts: 53
|
Posted: Wed Sep 29, 2004 3:07 pm Post subject: |
|
|
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 |
|
Back to top |
|
![](templates/subSilver/images/spacer.gif) |
svanleent
Joined: 25 Sep 2004 Posts: 53
|
Posted: Fri Oct 08, 2004 4:01 am Post subject: |
|
|
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 |
|
Back to top |
|
![](templates/subSilver/images/spacer.gif) |
Hohums
Joined: 08 Apr 2004 Posts: 71 Location: Western Australia
|
Posted: Mon Nov 08, 2004 4:55 am Post subject: |
|
|
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/ |
|
Back to top |
|
![](templates/subSilver/images/spacer.gif) |
svanleent
Joined: 25 Sep 2004 Posts: 53
|
Posted: Mon Nov 08, 2004 4:11 pm Post subject: |
|
|
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 |
|
Back to top |
|
![](templates/subSilver/images/spacer.gif) |
BenHinkle
Joined: 27 Mar 2004 Posts: 76
|
Posted: Wed Jan 19, 2005 7:31 am Post subject: ddoc style |
|
|
how do I vote? I'll just post my vote. I prefer JavaDoc style over Qt though supporting both would be great. |
|
Back to top |
|
![](templates/subSilver/images/spacer.gif) |
BenHinkle
Joined: 27 Mar 2004 Posts: 76
|
Posted: Wed Jan 19, 2005 7:32 am Post subject: Re: ddoc style |
|
|
BenHinkle wrote: | how do I vote? |
Oh, I see. after I logged in I could vote. |
|
Back to top |
|
![](templates/subSilver/images/spacer.gif) |
svanleent
Joined: 25 Sep 2004 Posts: 53
|
Posted: Wed Jan 19, 2005 4:41 pm Post subject: |
|
|
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 |
|
Back to top |
|
![](templates/subSilver/images/spacer.gif) |
kris
Joined: 27 Mar 2004 Posts: 1494 Location: South Pacific
|
Posted: Wed Jan 19, 2005 5:51 pm Post subject: |
|
|
svanleent wrote: | 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;
} |
Can you make the comment-recognizer be pluggable? That way, the effort might be spread around. In addition, there are some comment forms that are slight variations on other themes -- it would be good to support those too, and a pluggable approach might alleviate some issues there.
In particular, I'm talking about the comment style used in Mango -- a type of Javadoc which some processors do not recognize by default:
/*********************
this is a comment;
and another line
and another
*********************/
placing '*' in the left hand column for each comment line has always bothered me, since it screws up the auto-indentation feature of text-editors. Hence, the above comment style is 'open', so the drudgery of documentation is not painful as well
Javadoc handles the above case, but Doxygen does not (by default) |
|
Back to top |
|
![](templates/subSilver/images/spacer.gif) |
svanleent
Joined: 25 Sep 2004 Posts: 53
|
Posted: Sun Jan 30, 2005 7:35 pm Post subject: |
|
|
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 |
|
Back to top |
|
![](templates/subSilver/images/spacer.gif) |
|