FAQFAQ   SearchSearch   MemberlistMemberlist   UsergroupsUsergroups   RegisterRegister 
 ProfileProfile   Log in to check your private messagesLog in to check your private messages   Log inLog in 

DDoc Documentation Generation for D
Goto page 1, 2  Next
 
Post new topic   Reply to topic     Forum Index -> DDoc
View previous topic :: View next topic  

DDoc should use ... syntax in source files
Javadoc
14%
 14%  [ 2 ]
Qt
42%
 42%  [ 6 ]
XML-like
35%
 35%  [ 5 ]
Other
7%
 7%  [ 1 ]
Total Votes : 14

Author Message
svanleent



Joined: 25 Sep 2004
Posts: 53

PostPosted: Sat Sep 25, 2004 8:44 am    Post subject: DDoc Documentation Generation for D Reply with quote

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
View user's profile Send private message Send e-mail Yahoo Messenger MSN Messenger
larsivi
Site Admin


Joined: 27 Mar 2004
Posts: 453
Location: Trondheim, Norway

PostPosted: Sat Sep 25, 2004 2:30 pm    Post subject: Reply with quote

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. Wink I dropped it, probably because I wanted it to be very easy to extend, ironically making a complex solution.
Back to top
View user's profile Send private message
svanleent



Joined: 25 Sep 2004
Posts: 53

PostPosted: Sat Sep 25, 2004 3:14 pm    Post subject: Reply with quote

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 Crying or Very sad. 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
View user's profile Send private message Send e-mail Yahoo Messenger MSN Messenger
HelmutLeitner



Joined: 28 May 2004
Posts: 5
Location: Graz, Austria

PostPosted: Tue Sep 28, 2004 1:44 am    Post subject: Reply with quote

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
View user's profile Send private message
svanleent



Joined: 25 Sep 2004
Posts: 53

PostPosted: Tue Sep 28, 2004 3:29 am    Post subject: Reply with quote

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
View user's profile Send private message Send e-mail Yahoo Messenger MSN Messenger
smjg



Joined: 29 Sep 2004
Posts: 41

PostPosted: Wed Sep 29, 2004 11:59 am    Post subject: Reply with quote

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
View user's profile Send private message
svanleent



Joined: 25 Sep 2004
Posts: 53

PostPosted: Wed Sep 29, 2004 3:07 pm    Post subject: Reply with quote

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
View user's profile Send private message Send e-mail Yahoo Messenger MSN Messenger
svanleent



Joined: 25 Sep 2004
Posts: 53

PostPosted: Fri Oct 08, 2004 4:01 am    Post subject: Reply with quote

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
View user's profile Send private message Send e-mail Yahoo Messenger MSN Messenger
Hohums



Joined: 08 Apr 2004
Posts: 71
Location: Western Australia

PostPosted: Mon Nov 08, 2004 4:55 am    Post subject: Reply with quote

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
View user's profile Send private message AIM Address Yahoo Messenger MSN Messenger
svanleent



Joined: 25 Sep 2004
Posts: 53

PostPosted: Mon Nov 08, 2004 4:11 pm    Post subject: Reply with quote

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
View user's profile Send private message Send e-mail Yahoo Messenger MSN Messenger
BenHinkle



Joined: 27 Mar 2004
Posts: 76

PostPosted: Wed Jan 19, 2005 7:31 am    Post subject: ddoc style Reply with quote

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
View user's profile Send private message
BenHinkle



Joined: 27 Mar 2004
Posts: 76

PostPosted: Wed Jan 19, 2005 7:32 am    Post subject: Re: ddoc style Reply with quote

BenHinkle wrote:
how do I vote?

Oh, I see. after I logged in I could vote.
Back to top
View user's profile Send private message
svanleent



Joined: 25 Sep 2004
Posts: 53

PostPosted: Wed Jan 19, 2005 4:41 pm    Post subject: Reply with quote

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
View user's profile Send private message Send e-mail Yahoo Messenger MSN Messenger
kris



Joined: 27 Mar 2004
Posts: 1494
Location: South Pacific

PostPosted: Wed Jan 19, 2005 5:51 pm    Post subject: Reply with quote

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 Sad

Javadoc handles the above case, but Doxygen does not (by default)
Back to top
View user's profile Send private message
svanleent



Joined: 25 Sep 2004
Posts: 53

PostPosted: Sun Jan 30, 2005 7:35 pm    Post subject: Reply with quote

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
View user's profile Send private message Send e-mail Yahoo Messenger MSN Messenger
Display posts from previous:   
Post new topic   Reply to topic     Forum Index -> DDoc All times are GMT - 6 Hours
Goto page 1, 2  Next
Page 1 of 2

 
Jump to:  
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum


Powered by phpBB © 2001, 2005 phpBB Group