www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.announce - DMD 0.132 release - introducing the new Ddoc documentation generator

reply "Walter Bright" <newshound digitalmars.com> writes:
No bugs fixed, just the new Ddoc documentation generator. It's not perfect,
and the presentation highlighting and layout is more utilitarian than
sublime, but it really does cut down on the work of generating reasonable
looking documentation by about half.

I also found several errors in the pages converted to Ddoc format -
inconsistencies between the code and the previous documentation. Hopefully,
Ddoc will relegate such errors to the past.

It's pretty close to what we discussed in the newsgroup recently. Thanks to
all for the very helpful suggestions.

http://www.digitalmars.com/d/changelog.html

Ddoc spec:

www.digitalmars.com/d/ddoc.html

Sample pages generated by Ddoc:

www.digitalmars.com/d/phobos/std_math.html
www.digitalmars.com/d/phobos/std_path.html
www.digitalmars.com/d/phobos/std_outbuffer.html
www.digitalmars.com/d/phobos/std_stream.html
Sep 19 2005
next sibling parent reply Derek Parnell <derek psych.ward> writes:
On Mon, 19 Sep 2005 18:07:00 -0700, Walter Bright wrote:


 No bugs fixed, just the new Ddoc documentation generator. It's not perfect,
 and the presentation highlighting and layout is more utilitarian than
 sublime, but it really does cut down on the work of generating reasonable
 looking documentation by about half.



Thanks Walter. I'm sure this is a step in the right direction, and although
it may be a bit wobbly just now, it can only improve.
-- 
Derek
(skype: derek.j.parnell)
Melbourne, Australia
20/09/2005 11:11:55 AM
Sep 19 2005
parent "Walter Bright" <newshound digitalmars.com> writes:
"Derek Parnell" <derek psych.ward> wrote in message
news:vvo2v3iu7v23.twof8i1rkv2y$.dlg 40tude.net...

 On Mon, 19 Sep 2005 18:07:00 -0700, Walter Bright wrote:


 No bugs fixed, just the new Ddoc documentation generator. It's not







 and the presentation highlighting and layout is more utilitarian than
 sublime, but it really does cut down on the work of generating







 looking documentation by about half.



 Thanks Walter. I'm sure this is a step in the right direction, and




 it may be a bit wobbly just now, it can only improve.



The neat thing about it is that it can be used now. When Ddoc improves, all
you'll need to do is rerun it to regenerate the documentation, and voila! It
provides a nice independence from the vagaries of an ever-changing HTML
specification.

For example, right now it doesn't do color syntax highlighting of example
code. If this gets implemented in Ddoc, then everyone will get color syntax
highlighting automatically.
Sep 19 2005
prev sibling next sibling parent reply Derek Parnell <derek psych.ward> writes:
On Mon, 19 Sep 2005 18:07:00 -0700, Walter Bright wrote:


 No bugs fixed, just the new Ddoc documentation generator.



I'm disappointed that you choose to write the documentation generator in
C++ and not D.

-- 
Derek
(skype: derek.j.parnell)
Melbourne, Australia
20/09/2005 11:35:29 AM
Sep 19 2005
parent reply Derek Parnell <derek psych.ward> writes:
On Tue, 20 Sep 2005 11:36:25 +1000, Derek Parnell wrote:


 On Mon, 19 Sep 2005 18:07:00 -0700, Walter Bright wrote:
 

 No bugs fixed, just the new Ddoc documentation generator.



 I'm disappointed that you choose to write the documentation generator in
 C++ and not D.



However I can understand why; Ddoc being tightly integrated into the DMD
product. And this will also encourage alterative generators to be written.

-- 
Derek
(skype: derek.j.parnell)
Melbourne, Australia
20/09/2005 11:41:54 AM
Sep 19 2005
parent "Walter Bright" <newshound digitalmars.com> writes:
"Derek Parnell" <derek psych.ward> wrote in message
news:169ddipz4iv9l$.1hlvi166y9g2q$.dlg 40tude.net...

 On Tue, 20 Sep 2005 11:36:25 +1000, Derek Parnell wrote:


 On Mon, 19 Sep 2005 18:07:00 -0700, Walter Bright wrote:


 No bugs fixed, just the new Ddoc documentation generator.



 I'm disappointed that you choose to write the documentation generator in
 C++ and not D.






So am I. It would have been significantly less work to write it in D.


 However I can understand why; Ddoc being tightly integrated into the DMD
 product.



Yes, it relies on the rest of the front end.


 And this will also encourage alterative generators to be written.



That's why it's all in doc.h and doc.c. Upgrading it should be fairly easy.
Sep 19 2005
prev sibling next sibling parent David L. Davis <SpottedTiger yahoo.com> writes:
In article <dgnng9$2tb8$1 digitaldaemon.com>, Walter Bright says...

No bugs fixed, just the new Ddoc documentation generator. It's not perfect,
and the presentation highlighting and layout is more utilitarian than
sublime, but it really does cut down on the work of generating reasonable
looking documentation by about half.

I also found several errors in the pages converted to Ddoc format -
inconsistencies between the code and the previous documentation. Hopefully,
Ddoc will relegate such errors to the past.

It's pretty close to what we discussed in the newsgroup recently. Thanks to
all for the very helpful suggestions.

http://www.digitalmars.com/d/changelog.html

Ddoc spec:

www.digitalmars.com/d/ddoc.html

Sample pages generated by Ddoc:

www.digitalmars.com/d/phobos/std_math.html
www.digitalmars.com/d/phobos/std_path.html
www.digitalmars.com/d/phobos/std_outbuffer.html
www.digitalmars.com/d/phobos/std_stream.html



Kool! I'll have to try it out. :)

David L.

-------------------------------------------------------------------
"Dare to reach for the Stars...Dare to Dream, Build, and Achieve!"
-------------------------------------------------------------------

MKoD: http://spottedtiger.tripod.com/D_Language/D_Main_XP.html
Sep 19 2005
prev sibling next sibling parent reply clayasaurus <clayasaurus gmail.com> writes:
Walter Bright wrote:

 No bugs fixed, just the new Ddoc documentation generator. It's not perfect,
 and the presentation highlighting and layout is more utilitarian than
 sublime, but it really does cut down on the work of generating reasonable
 looking documentation by about half.
 
 I also found several errors in the pages converted to Ddoc format -
 inconsistencies between the code and the previous documentation. Hopefully,
 Ddoc will relegate such errors to the past.
 
 It's pretty close to what we discussed in the newsgroup recently. Thanks to
 all for the very helpful suggestions.
 
 http://www.digitalmars.com/d/changelog.html
 
 Ddoc spec:
 
 www.digitalmars.com/d/ddoc.html
 
 Sample pages generated by Ddoc:
 
 www.digitalmars.com/d/phobos/std_math.html
 www.digitalmars.com/d/phobos/std_path.html
 www.digitalmars.com/d/phobos/std_outbuffer.html
 www.digitalmars.com/d/phobos/std_stream.html
 
 



Now there is no excuse for not having decent documentation : )

Thanks.
Sep 19 2005
next sibling parent Derek Parnell <derek psych.ward> writes:
On Mon, 19 Sep 2005 23:57:22 -0400, clayasaurus wrote:


 Walter Bright wrote:

 No bugs fixed, just the new Ddoc documentation generator. 







 Now there is no excuse for not having decent documentation : )



We must not confuse form with content ;-)

-- 
Derek
(skype: derek.j.parnell)
Melbourne, Australia
20/09/2005 2:18:58 PM
Sep 19 2005
prev sibling parent Stewart Gordon <smjg_1998 yahoo.com> writes:
clayasaurus wrote:
<snip>

 Now there is no excuse for not having decent documentation : )



Not sure about that - part of being decent is being valid according to 
the format it purports to be in.

Stewart.

-- 
-----BEGIN GEEK CODE BLOCK-----
Version: 3.1
GCS/M d- s:- C++  a->--- UB  P+ L E  W++  N+++ o K-  w++  O? M V? PS- 
PE- Y? PGP- t- 5? X? R b DI? D G e++>++++ h-- r-- !y
------END GEEK CODE BLOCK------

My e-mail is valid but not my primary mailbox.  Please keep replies on 
the 'group where everyone may benefit.
Sep 20 2005
prev sibling next sibling parent Stewart Gordon <smjg_1998 yahoo.com> writes:
Walter Bright wrote:
<snip>

 Sample pages generated by Ddoc:
 
 www.digitalmars.com/d/phobos/std_math.html
 www.digitalmars.com/d/phobos/std_path.html



Already noticed a bug: it drops spaces, screwing up wordwrapping

const char[1]sep;
char[] defaultExt(char[]filename,char[]ext);

ought to be

const char[1] sep;
char[] defaultExt(char[] filename, char[] ext);

Stewart.

-- 
-----BEGIN GEEK CODE BLOCK-----
Version: 3.1
GCS/M d- s:- C++  a->--- UB  P+ L E  W++  N+++ o K-  w++  O? M V? PS- 
PE- Y? PGP- t- 5? X? R b DI? D G e++>++++ h-- r-- !y
------END GEEK CODE BLOCK------

My e-mail is valid but not my primary mailbox.  Please keep replies on 
the 'group where everyone may benefit.
Sep 20 2005
prev sibling next sibling parent reply David L. Davis <SpottedTiger yahoo.com> writes:
In article <dgnng9$2tb8$1 digitaldaemon.com>, Walter Bright says...

No bugs fixed, just the new Ddoc documentation generator. It's not perfect,
and the presentation highlighting and layout is more utilitarian than
sublime, but it really does cut down on the work of generating reasonable
looking documentation by about half.



Walter, Ddoc doesn't seem to like templates in the source, I get an error when I
run the below D source with the -D switch.

(Sample test for Ddoc)

# /** 
#  * <font face="Courier New"> 
#  * <li>Source          : isNegative.d </li>
#  * <li>Author          : David L. 'SpottedTiger' Davis</li>
#  * <li>D Compiler      : dmd v0.131</li>
#  * <li>Source Platform : Intel x86 / WinXP SP2</li>
#  * <li>Target Platform : An Intel x86-Based OS like MS Windows</li>  
#  * </font>
#  */
#
# /+ When uncommented, an error occurs
# template isNegative(T)
# {
#     bool isNegative(out T v) { return true; }	
# }
# +/
#
# debug( isneg )
# {
# int main()
# {
#     return 0;
# } 
# }

Output using "dmd isneg.d -D -debug=isneg" :
---------
doctest

int main(); 

Source : isNegative.d 
Author : David L. 'SpottedTiger' Davis 
D Compiler : dmd v0.131 
Source Platform : Intel x86 / WinXP SP2 
Target Platform : An Intel x86-Based OS like MS Windows 

--------------------------------------------------------------------------
Last modified: Tue Sep 20 13:03:20 2005 

Also why does the top comments end up under the very first function? Plus I
thought that if I wrapped my comments with the "<li>  </li>" tags that my spaces
would remain as is (I used a fixed-width font like "Courier New"), but they're
still pulled out.

Well, as in anything new, there are always some growing pains to work though,
and Walter I do want to thank you for what you've done on the Ddoc feature thus
far. But, I really hope it doesn't take you away from fixing bugs for too long,
and I'd still love to see D v1.0 out the door sometime in the near future. <g>

David L.

-------------------------------------------------------------------
"Dare to reach for the Stars...Dare to Dream, Build, and Achieve!"
-------------------------------------------------------------------

MKoD: http://spottedtiger.tripod.com/D_Language/D_Main_XP.html
Sep 20 2005
parent reply "Walter Bright" <newshound digitalmars.com> writes:
"David L. Davis" <SpottedTiger yahoo.com> wrote in message
news:dgpgjc$1gqt$1 digitaldaemon.com...

 Also why does the top comments end up under the very first function?



Because that's the first declaration following them. Adding a module
declaration should resolve it.


 Plus I
 thought that if I wrapped my comments with the "<li>  </li>" tags that my




 would remain as is (I used a fixed-width font like "Courier New"), but




 still pulled out.



No. You'll need to use <pre> or &nbsp;. <tt> might work.


 Well, as in anything new, there are always some growing pains to work




 and Walter I do want to thank you for what you've done on the Ddoc feature




 far. But, I really hope it doesn't take you away from fixing bugs for too




 and I'd still love to see D v1.0 out the door sometime in the near future.




Documentation that sucks is holding D back. Ddoc will cut the effort needed
to write new documentation by about 50%, and will cut by 99% the effort
needed to upgrade to a better presentation. (I won't have to edit scores of
files by hand anymore.)
Sep 20 2005
parent David L. Davis <SpottedTiger yahoo.com> writes:
In article <dgplnc$1lts$1 digitaldaemon.com>, Walter Bright says...

"David L. Davis" <SpottedTiger yahoo.com> wrote in message
news:dgpgjc$1gqt$1 digitaldaemon.com...

 Also why does the top comments end up under the very first function?



Because that's the first declaration following them. Adding a module
declaration should resolve it.



Adding a "module isneg;" did solve this issue...but unless I missed it, I did't
see this piece of information in Ddoc documentation. Could you please add it in.
Thanks. 


 Plus I
 thought that if I wrapped my comments with the "<li>  </li>" tags that my




 would remain as is (I used a fixed-width font like "Courier New"), but




 still pulled out.



No. You'll need to use <pre> or &nbsp;. <tt> might work.



Excellent! The "<pre><tt>Author    : Whoever</tt></pre>" worked great, all my
whitespace stayed in place. <g>


 Well, as in anything new, there are always some growing pains to work




 and Walter I do want to thank you for what you've done on the Ddoc feature




 far. But, I really hope it doesn't take you away from fixing bugs for too




 and I'd still love to see D v1.0 out the door sometime in the near future.




Documentation that sucks is holding D back. Ddoc will cut the effort needed
to write new documentation by about 50%, and will cut by 99% the effort
needed to upgrade to a better presentation. (I won't have to edit scores of
files by hand anymore.)



Roger! I agree. It is time well spend improving the documentation, especially if
it's saving your time on moving D forward! And it's very useful / helpful for
the rest of us as well.

David L.

-------------------------------------------------------------------
"Dare to reach for the Stars...Dare to Dream, Build, and Achieve!"
-------------------------------------------------------------------
Sep 20 2005
prev sibling next sibling parent Sean Kelly <sean f4.ca> writes:
Awesome!  A few thoughts that I had while playing with this:

It would be nice if there were a way to run the documenter without generating an
object file.

If the destination path does not exist, there should be an option to have it
created (or perhaps this should be the default behavior).

There should be an option to have the destination path mimic the module name.
For example, if I have three modules:

module mylib.p1.m1;
module mylib.p1.m2;
module mylib.p2.m1;

The files would go in these directories:

mylib/p1
mylib/p1
mylib/p2

We need a way to document templates, and embedded code should retain the
template parameter names if instantiation is required.  ie.

template fn(T) {
T fn() {}
}

should be documented as returning a value of type T.

I'll admit to not having tried documenting templates yet, so perhaps it already
works this way.  My only other issues at the moment have to do with formatting:
documenting classes is somewhat confusing because the output does not make it
clear which elements are class members.


Sean
Sep 20 2005
prev sibling next sibling parent reply James Dunne <james.jdunne gmail.com> writes:
Walter Bright wrote:

 No bugs fixed, just the new Ddoc documentation generator. It's not perfect,
 and the presentation highlighting and layout is more utilitarian than
 sublime, but it really does cut down on the work of generating reasonable
 looking documentation by about half.
 
 I also found several errors in the pages converted to Ddoc format -
 inconsistencies between the code and the previous documentation. Hopefully,
 Ddoc will relegate such errors to the past.
 
 It's pretty close to what we discussed in the newsgroup recently. Thanks to
 all for the very helpful suggestions.
 
 http://www.digitalmars.com/d/changelog.html
 
 Ddoc spec:
 
 www.digitalmars.com/d/ddoc.html
 
 Sample pages generated by Ddoc:
 
 www.digitalmars.com/d/phobos/std_math.html
 www.digitalmars.com/d/phobos/std_path.html
 www.digitalmars.com/d/phobos/std_outbuffer.html
 www.digitalmars.com/d/phobos/std_stream.html
 
 



Very nice.

How do we control (from Ddoc) the emphasis used on highlighted example 
code?  There should be some Ddoc special section for emphasis to define 
how to emphasize keywords, operators, whitespace, identifiers, etc.
Sep 20 2005
parent reply "Walter Bright" <newshound digitalmars.com> writes:
"James Dunne" <james.jdunne gmail.com> wrote in message
news:dgpj8r$1j8d$1 digitaldaemon.com...

 How do we control (from Ddoc) the emphasis used on highlighted example
 code?  There should be some Ddoc special section for emphasis to define
 how to emphasize keywords, operators, whitespace, identifiers, etc.



Currently, it's not possible unless you do it manually using <pre> ...
</pre> tags.

Eventually, I'd like to improve the code highlighter to wrap each grammar
element in a style tag, and then with a style sheet you'll be able to
completely control the emphasis on example code.
Sep 20 2005
next sibling parent James Dunne <james.jdunne gmail.com> writes:
Walter Bright wrote:

 "James Dunne" <james.jdunne gmail.com> wrote in message
 news:dgpj8r$1j8d$1 digitaldaemon.com...
 

How do we control (from Ddoc) the emphasis used on highlighted example
code?  There should be some Ddoc special section for emphasis to define
how to emphasize keywords, operators, whitespace, identifiers, etc.



 
 Currently, it's not possible unless you do it manually using <pre> ...
 </pre> tags.
 
 Eventually, I'd like to improve the code highlighter to wrap each grammar
 element in a style tag, and then with a style sheet you'll be able to
 completely control the emphasis on example code.
 



Precisely what I meant. =P
Sep 20 2005
prev sibling parent "Charles" <noone nowhere.com> writes:
"Walter Bright" <newshound digitalmars.com> wrote in message
news:dgpmsk$1n46$1 digitaldaemon.com...

 "James Dunne" <james.jdunne gmail.com> wrote in message
 news:dgpj8r$1j8d$1 digitaldaemon.com...

 How do we control (from Ddoc) the emphasis used on highlighted example
 code?  There should be some Ddoc special section for emphasis to define
 how to emphasize keywords, operators, whitespace, identifiers, etc.



 Currently, it's not possible unless you do it manually using <pre> ...
 </pre> tags.

 Eventually, I'd like to improve the code highlighter to wrap each grammar
 element in a style tag, and then with a style sheet you'll be able to
 completely control the emphasis on example code.



Awesome idea
Sep 20 2005
prev sibling parent reply "Kris" <fu bar.com> writes:
Nice!

I tried it on Mango, but it GPF'd quite quickly. As you say, it's a good
start.

I'd like to suggest a few things:

1)

# /********************
#    this kind of comment
# ********************/

winds up like this:

# this kind of comment *****************

can that be resolved by the doc generator?


2) clickable links between the various files/symbols add a huge amount of
value

3) it would be nice to support custom rendering for the various
documentation sections.

4) private classes are included. Should they be?

5) a distinction between overridden methods, abstract methods, and so on
would be very useful. I mean, perhaps located in a seperate section?

6) a "project description" page, or pages, are really useful for guiding the
uninitiated. Doxygen supports this via the  mainpage directive, and
references to other parts of the doc are automatically generated ~ one of
the better features of Doxygen (I think).

- Kris




"Walter Bright" <newshound digitalmars.com> wrote in message
news:dgnng9$2tb8$1 digitaldaemon.com...

 No bugs fixed, just the new Ddoc documentation generator. It's not




 and the presentation highlighting and layout is more utilitarian than
 sublime, but it really does cut down on the work of generating reasonable
 looking documentation by about half.

 I also found several errors in the pages converted to Ddoc format -
 inconsistencies between the code and the previous documentation.




 Ddoc will relegate such errors to the past.

 It's pretty close to what we discussed in the newsgroup recently. Thanks




 all for the very helpful suggestions.

 http://www.digitalmars.com/d/changelog.html

 Ddoc spec:

 www.digitalmars.com/d/ddoc.html

 Sample pages generated by Ddoc:

 www.digitalmars.com/d/phobos/std_math.html
 www.digitalmars.com/d/phobos/std_path.html
 www.digitalmars.com/d/phobos/std_outbuffer.html
 www.digitalmars.com/d/phobos/std_stream.html
Sep 21 2005
parent "Walter Bright" <newshound digitalmars.com> writes:
"Kris" <fu bar.com> wrote in message news:dgt754$2a44$1 digitaldaemon.com...

 Nice!

 I tried it on Mango, but it GPF'd quite quickly. As you say, it's a good
 start.



I'm working on it at the moment, so if you could send me a snippet that
causes this, I can get it fixed!
Sep 22 2005