www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - TLC for ddox

reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
Whenever I look at the documentation, I find things that could be 
improved. Consider https://dlang.org/library/, one of the most important 
pages - the portal - of the hopefully future default documentation 
renderer. It goes something like this:

================
Module	Description
================
std.algorithm.comparison	This is a submodule of std.algorithm. It 
contains generic comparison algorithms.
std.algorithm.iteration	This is a submodule of std.algorithm. It 
contains generic iteration algorithms.
std.algorithm.mutation	This is a submodule of std.algorithm. It contains 
generic mutation algorithms.
std.algorithm.searching	This is a submodule of std.algorithm. It 
contains generic searching algorithms.
...
================

Makes you want to go postal, innit? Reminds me of this quote from David 
Foster Wallace's unfinished The Pale King: 
https://www.goodreads.com/quotes/621837-irrelevant-chris-fogle-turns-a-page-howard-cardwell-turns-a

Can a kind volunteer please put some tender love care into that page?


Thanks,

Andrei
Nov 16
next sibling parent Seb <seb wilzba.ch> writes:
On Friday, 17 November 2017 at 03:04:20 UTC, Andrei Alexandrescu 
wrote:
 Whenever I look at the documentation, I find things that could 
 be improved. Consider https://dlang.org/library/, one of the 
 most important pages - the portal - of the hopefully future 
 default documentation renderer. It goes something like this:

 ================
 Module	Description
 ================
 std.algorithm.comparison	This is a submodule of std.algorithm. 
 It contains generic comparison algorithms.
 std.algorithm.iteration	This is a submodule of std.algorithm. 
 It contains generic iteration algorithms.
 std.algorithm.mutation	This is a submodule of std.algorithm. It 
 contains generic mutation algorithms.
 std.algorithm.searching	This is a submodule of std.algorithm. 
 It contains generic searching algorithms.
 ...
 ================

 Makes you want to go postal, innit? Reminds me of this quote 
 from David Foster Wallace's unfinished The Pale King: 
 https://www.goodreads.com/quotes/621837-irrelevant-chris-fogle-turns-a-page-howard-cardwell-turns-a

 Can a kind volunteer please put some tender love care into that 
 page?


 Thanks,

 Andrei
This has already been partially fixed at ddox[1], but we can't upgrade ddox for the dlang.org build atm [2]. [1] https://github.com/rejectedsoftware/ddox/pull/165 [2] https://github.com/dlang/dlang.org/pull/1891
Nov 17
prev sibling parent Adam D. Ruppe <destructionator gmail.com> writes:
On Friday, 17 November 2017 at 03:04:20 UTC, Andrei Alexandrescu 
wrote:
 Whenever I look at the documentation, I find things that could 
 be improved. [...]
 Makes you want to go postal, innit?
Makes me want to go "fork"-al. http://dpldocs.info/experimental-docs/std.html http://dpldocs.info/experimental-docs/std.algorithm.html There's still stuff I'm not quite happy with, but a huge win on my site is that I change the generator and source code in sync - some of the problems you have pointed out with ddox are the generator's fault and some are Phobos source code tweaks. I think if ddox is going to have similar success, I think the "website doc czar" on your end will have to have authority to edit doc comments in a streamlined process as well as the doc generator. They go hand-in-hand.
Nov 17