View mode: basic / threaded / horizontal-split · Log in · Help
September 29, 2012
Re: Getting started with D - Phobos documentation sucks
On Saturday, 29 September 2012 at 17:03:26 UTC, monarch_dodra 
wrote:
> Well, they *are* better than nothing at all. Sure, in the best 
> of worlds, we'd have lovingly hand written indexes and 
> documentation, such as for std_algorithm. However, for those 
> modules that *don't* have that hand written doc, it is better 
> than nothing.

It is possible to do something like that automatically:

http://arsdnet.net/d-web-site/std_stdio.html
http://arsdnet.net/d-web-site/std_datetime.html
September 29, 2012
Re: Getting started with D - Phobos documentation sucks
Le 29/09/2012 19:09, Adam D. Ruppe a écrit :
> On Saturday, 29 September 2012 at 17:03:26 UTC, monarch_dodra wrote:
>> Well, they *are* better than nothing at all. Sure, in the best of
>> worlds, we'd have lovingly hand written indexes and documentation,
>> such as for std_algorithm. However, for those modules that *don't*
>> have that hand written doc, it is better than nothing.
>
> It is possible to do something like that automatically:
>
> http://arsdnet.net/d-web-site/std_stdio.html
> http://arsdnet.net/d-web-site/std_datetime.html
>

That is much better than what we currently have.
September 29, 2012
Re: Getting started with D - Phobos documentation sucks
On 29-Sep-12 21:13, deadalnix wrote:
> Le 29/09/2012 19:09, Adam D. Ruppe a écrit :
>> On Saturday, 29 September 2012 at 17:03:26 UTC, monarch_dodra wrote:
>>> Well, they *are* better than nothing at all. Sure, in the best of
>>> worlds, we'd have lovingly hand written indexes and documentation,
>>> such as for std_algorithm. However, for those modules that *don't*
>>> have that hand written doc, it is better than nothing.
>>
>> It is possible to do something like that automatically:
>>
>> http://arsdnet.net/d-web-site/std_stdio.html
>> http://arsdnet.net/d-web-site/std_datetime.html
>>
>
> That is much better than what we currently have.

Agreed. What's needed to make it a reality ?

-- 
Dmitry Olshansky
September 30, 2012
Re: Getting started with D - Phobos documentation sucks
On Saturday, 29 September 2012 at 17:20:48 UTC, Dmitry Olshansky 
wrote:
> Agreed. What's needed to make it a reality ?

Need to integrate my helper program into the website build 
process.

Program here:
http://arsdnet.net/d-web-site/improveddoc.d

libs needed
https://github.com/adamdruppe/misc-stuff-including-D-programming-language-web-stuff

dom.d and characterencodings.d



When I tried this earlier, I couldn't even get the basic website 
to build on my box from github. I think it needs github phobos 
too but meh, I moved on to something else and never got back to 
it.

But if the website makefile built and ran that program across the 
html it generates, it should be set.
September 30, 2012
Re: Getting started with D - Phobos documentation sucks
On Sunday, September 30, 2012 04:17:59 Adam D. Ruppe wrote:
> When I tried this earlier, I couldn't even get the basic website
> to build on my box from github. I think it needs github phobos
> too but meh, I moved on to something else and never got back to
> it.

Unless something's changed recently, to build the website docs, you need both 
druntime and Phobos to be the latest from github (just like d-programming-
language.org) and to have them all in the same directory. Otherwise, it 
doesn't work. And personally, I'm always having to change the makefile so that 
it doesn't try and build previous versions of Phobos or it doesn't work. It's 
far too dependent on having a very specific setup on your box and probably 
should be fixed as part of the initiatize to better automize the release 
process. It's far too fragile as it is.

- Jonathan M Davis
September 30, 2012
Re: Getting started with D - Phobos documentation sucks
On 30-Sep-12 06:17, Adam D. Ruppe wrote:
> On Saturday, 29 September 2012 at 17:20:48 UTC, Dmitry Olshansky wrote:
>> Agreed. What's needed to make it a reality ?
>
> Need to integrate my helper program into the website build process.
>
> Program here:
> http://arsdnet.net/d-web-site/improveddoc.d
>
> libs needed
> https://github.com/adamdruppe/misc-stuff-including-D-programming-language-web-stuff
>
>
> dom.d and characterencodings.d
>
>
>
> When I tried this earlier, I couldn't even get the basic website to
> build on my box from github. I think it needs github phobos too but meh,
> I moved on to something else and never got back to it.
>
> But if the website makefile built and ran that program across the html
> it generates, it should be set.

I'll give it a whirl. The current auto generated _index_ at the top is 
intolerable.
It won't surprise me if this alone has attributed to having say 20% less 
newcomers. Not to mention some cool functions that just got lost in this 
noise :)

-- 
Dmitry Olshansky
September 30, 2012
Re: Getting started with D - Phobos documentation sucks
On 2012-09-30 04:17, Adam D. Ruppe wrote:
> On Saturday, 29 September 2012 at 17:20:48 UTC, Dmitry Olshansky wrote:
>> Agreed. What's needed to make it a reality ?
>
> Need to integrate my helper program into the website build process.

Is it just me that thinks that having a tool that fixes the generated 
documentation is ridiculous. The compiler should be modified to generate 
the documentation we want to have.

-- 
/Jacob Carlborg
September 30, 2012
Re: Getting started with D - Phobos documentation sucks
On Sunday, September 30, 2012 13:02:15 Jacob Carlborg wrote:
> On 2012-09-30 04:17, Adam D. Ruppe wrote:
> > On Saturday, 29 September 2012 at 17:20:48 UTC, Dmitry Olshansky wrote:
> >> Agreed. What's needed to make it a reality ?
> > 
> > Need to integrate my helper program into the website build process.
> 
> Is it just me that thinks that having a tool that fixes the generated
> documentation is ridiculous. The compiler should be modified to generate
> the documentation we want to have.

That's what I've always thought. The main problem IMHO is how the links are 
generated, making it impossible to have links to symbols with the same name in 
the same module even if they're in different scopes (e.g. a free function and 
one in a class). And that's definitely not the sort of thing that an external 
tool should be fixing.

- Jonathan M Davis
September 30, 2012
Re: Getting started with D - Phobos documentation sucks
While we're speaking about docs improvement, I believe there is 
one more thing that could use a fix - clickable identifiers. I 
don't know how much of an effort it would require, so consider it 
a wishlist, but for stuff like:

static @property @safe TickDuration currAppTick();

TickDuration should be a clickable link leading to 
core.time.TickDuration class docs.

Example: 
http://docs.oracle.com/javase/1.4.2/docs/api/javax/swing/Icon.html#paintIcon(java.awt.Component, 
java.awt.Graphics, int, int)

notice how Component and Graphics are clickable so you can 
instantly jump to their relevant declarations. This feature along 
with the abovementioned improvements would probably make the 
documentation a useful and intuitive tool.
September 30, 2012
Re: Getting started with D - Phobos documentation sucks
On Sunday, 30 September 2012 at 11:22:02 UTC, Jonathan M Davis 
wrote:
> The main problem IMHO is how the links are generated,
> making it impossible to have links to symbols with the
> same name in the same module

Yeah, I did a pull request to dmd to add a new macro to fix this, 
but I also included a change to the escaping rules and the powers 
that be weren't convinced of them (though they should be, ddoc is 
virtually unusable for documenting html and also for outputting 
other document formats without it or something like it).

Anyway though I need to separate out my ddoc fixes into 
individual pull requests and I haven't gotten around to it yet. 
Maybe I'll try to fit it in today.

After we allow a DDOC_PSYMBOL macro, we update std.ddoc to use it 
for the anchors and then we're set.



Though, it still doesn't account for overloaded functions... but 
meh it's a *lot* better than we have now.
1 2 3 4 5
Top | Discussion index | About this forum | D home