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

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.

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

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.

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

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

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

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

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.

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.