Doc improvements, compilation

[Brad Anderson]

On Monday, 29 July 2013 at 18:51:28 UTC, Luís Marques wrote:
> In the docs for std.format we have the following example:
>
>     import std.c.stdio;
>     import std.format;
>
>     void main()
>     {
>         auto writer = appender!string();
>         formattedWrite(writer, "%s is the ultimate %s.", 42, 
> "answer");
>         assert(writer.data == "42 is the ultimate answer.");
>         // Clear the writer
>         writer = appender!string();
>         formattedWrite(writer, "Date: %2$s %1$s", "October", 5);
>         assert(writer.data == "Date: 5 October");
>     }
>
> This does not compile because where it imports std.c.stdio it 
> should import instead std.array. Are the docs not being 
> compiled, to check for errors? Perhaps that could be improved, 
> by automatically compiling all the docs and checking for errors 
> (if they all should just compile then it's straightforward, 
> otherwise it would be necessary to tag them as 'should compile' 
> where appropriate, or by adding the necessary scaffolding to 
> ensure compilation).
>

The recently added unittests used for ddoc examples feature 
solves this but it requires people to go through and make the 
examples into unittests.

> The js "jump to" headers also seem not to be working well. In 
> std.conv I get (in both Chrome and Safari):
>
>     Improve this page _to!TargetType(value) (and not some 
> variant of toImpl)." class="button">Page wiki View or edit the 
> community-maintained wiki page associated with this page.
>

ddoc bug.  I've fixed this before on this page by tweaking the 
macro ordering but I didn't look into what's actually causing it.

https://github.com/D-Programming-Language/phobos/pull/1292

> In other pages it seems to work, but it is often very slow to 
> generate the jump to headers.
>
> --
> Luís

A recent pull makes the jump to list generate before the page is 
shown so we won't get it suddenly appearing anymore.  It's not 
the jump to list that's slow, it's hyphenate.js that is the 
bottleneck.  The jump list generation would happen after the slow 
page hyphenation occurred.