www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Doc improvements, compilation

reply =?UTF-8?B?Ikx1w61z?= Marques" <luismarques gmail.com> writes:
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 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.

In other pages it seems to work, but it is often very slow to 
generate the jump to headers.

--
Luís
Jul 29 2013
next sibling parent "Brad Anderson" <eco gnuk.net> writes:
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.
Jul 29 2013
prev sibling next sibling parent =?UTF-8?B?Ikx1w61z?= Marques" <luismarques gmail.com> writes:
On Monday, 29 July 2013 at 18:59:01 UTC, Brad Anderson wrote:
 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.

Does that slow the rest of the page to the time it currently takes for the jump list to be ready? If so, is that not problematic?
Jul 29 2013
prev sibling next sibling parent "Brad Anderson" <eco gnuk.net> writes:
On Monday, 29 July 2013 at 19:03:25 UTC, Luís Marques wrote:
 On Monday, 29 July 2013 at 18:59:01 UTC, Brad Anderson wrote:
 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.

Does that slow the rest of the page to the time it currently takes for the jump list to be ready? If so, is that not problematic?

I believe it just changed the ordering so that the jump list was made before the hyphenation pass but I could be wrong here.
Jul 29 2013
prev sibling parent "Brad Anderson" <eco gnuk.net> writes:
On Monday, 29 July 2013 at 19:06:12 UTC, Brad Anderson wrote:
 On Monday, 29 July 2013 at 19:03:25 UTC, Luís Marques wrote:
 On Monday, 29 July 2013 at 18:59:01 UTC, Brad Anderson wrote:
 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.

Does that slow the rest of the page to the time it currently takes for the jump list to be ready? If so, is that not problematic?

I believe it just changed the ordering so that the jump list was made before the hyphenation pass but I could be wrong here.

Here's the pull: https://github.com/D-Programming-Language/dlang.org/pull/365
Jul 29 2013