www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Ready to make page-per-item ddocs the default?

reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
Let's crowdsource the review. Please check the entries linked from here: 
http://dlang.org/library/index.html.

Andrei
Jan 06 2015
next sibling parent reply "weaselcat" <weaselcat gmail.com> writes:
On Tuesday, 6 January 2015 at 22:43:45 UTC, Andrei Alexandrescu 
wrote:
 Let's crowdsource the review. Please check the entries linked 
 from here: http://dlang.org/library/index.html.

 Andrei
Is it intentional for all of the stdc pages to be empty?
Jan 06 2015
next sibling parent "Brian Schott" <briancschott gmail.com> writes:
On Tuesday, 6 January 2015 at 23:44:30 UTC, weaselcat wrote:
 Is it intentional for all of the stdc pages to be empty?
I think it's intentional that they don't duplicate the documentation for those headers, but we probably should add links to pages that document the C headers.
Jan 06 2015
prev sibling next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/6/15 3:44 PM, weaselcat wrote:
 On Tuesday, 6 January 2015 at 22:43:45 UTC, Andrei Alexandrescu wrote:
 Let's crowdsource the review. Please check the entries linked from
 here: http://dlang.org/library/index.html.

 Andrei
Is it intentional for all of the stdc pages to be empty?
It's a somewhat unfortunate fallout of the level of granularity. I think each of these headers should include a standard text and a link to some good documentation in C-land. -- Andrei
Jan 06 2015
parent reply Steven Schveighoffer <schveiguy yahoo.com> writes:
On 1/6/15 8:16 PM, Andrei Alexandrescu wrote:
 On 1/6/15 3:44 PM, weaselcat wrote:
 On Tuesday, 6 January 2015 at 22:43:45 UTC, Andrei Alexandrescu wrote:
 Let's crowdsource the review. Please check the entries linked from
 here: http://dlang.org/library/index.html.

 Andrei
Is it intentional for all of the stdc pages to be empty?
It's a somewhat unfortunate fallout of the level of granularity. I think each of these headers should include a standard text and a link to some good documentation in C-land. -- Andrei
I like this idea. One thing that may be misleading about this -- our headers don't include *everything* from C-land. What would be a good generic blurb? strawman: core.stdc.ctype: "This contains bindings to selected types and functions from the standard C header <ctype.h> (see http://pubs.opengroup.org/onlinepubs/009695399/basedefs/ctype.h.html). Note that this is not automatically generated, and may omit some types/functions from the original C header." I'm thinking we should actually just put a /// before every symbol, to get it in the ddoc so you can see what *is* included. Thoughts? I can put together a pull for core.stdc.* if it makes sense. -Steve
Jan 08 2015
next sibling parent Jacob Carlborg <doob me.com> writes:
On 2015-01-08 13:18, Steven Schveighoffer wrote:

 I like this idea.

 One thing that may be misleading about this -- our headers don't include
 *everything* from C-land.

 What would be a good generic blurb? strawman:

 core.stdc.ctype:
 "This contains bindings to selected types and functions from the
 standard C header <ctype.h> (see
 http://pubs.opengroup.org/onlinepubs/009695399/basedefs/ctype.h.html).
 Note that this is not automatically generated, and may omit some
 types/functions from the original C header."

 I'm thinking we should actually just put a /// before every symbol, to
 get it in the ddoc so you can see what *is* included.

 Thoughts? I can put together a pull for core.stdc.* if it makes sense.
I like it. -- /Jacob Carlborg
Jan 08 2015
prev sibling next sibling parent "John Colvin" <john.loughran.colvin gmail.com> writes:
On Thursday, 8 January 2015 at 12:18:37 UTC, Steven Schveighoffer 
wrote:
 On 1/6/15 8:16 PM, Andrei Alexandrescu wrote:
 On 1/6/15 3:44 PM, weaselcat wrote:
 On Tuesday, 6 January 2015 at 22:43:45 UTC, Andrei 
 Alexandrescu wrote:
 Let's crowdsource the review. Please check the entries 
 linked from
 here: http://dlang.org/library/index.html.

 Andrei
Is it intentional for all of the stdc pages to be empty?
It's a somewhat unfortunate fallout of the level of granularity. I think each of these headers should include a standard text and a link to some good documentation in C-land. -- Andrei
I like this idea. One thing that may be misleading about this -- our headers don't include *everything* from C-land. What would be a good generic blurb? strawman: core.stdc.ctype: "This contains bindings to selected types and functions from the standard C header <ctype.h> (see http://pubs.opengroup.org/onlinepubs/009695399/basedefs/ctype.h.html). Note that this is not automatically generated, and may omit some types/functions from the original C header." I'm thinking we should actually just put a /// before every symbol, to get it in the ddoc so you can see what *is* included. Thoughts? I can put together a pull for core.stdc.* if it makes sense. -Steve
All public symbols in any module should have a ddoc comment, even if said comment is empty. Does that sound like a reasonable rule-of-thumb?
Jan 08 2015
prev sibling next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/8/15 4:18 AM, Steven Schveighoffer wrote:
 On 1/6/15 8:16 PM, Andrei Alexandrescu wrote:
 On 1/6/15 3:44 PM, weaselcat wrote:
 On Tuesday, 6 January 2015 at 22:43:45 UTC, Andrei Alexandrescu wrote:
 Let's crowdsource the review. Please check the entries linked from
 here: http://dlang.org/library/index.html.

 Andrei
Is it intentional for all of the stdc pages to be empty?
It's a somewhat unfortunate fallout of the level of granularity. I think each of these headers should include a standard text and a link to some good documentation in C-land. -- Andrei
I like this idea. One thing that may be misleading about this -- our headers don't include *everything* from C-land. What would be a good generic blurb? strawman: core.stdc.ctype: "This contains bindings to selected types and functions from the standard C header <ctype.h> (see http://pubs.opengroup.org/onlinepubs/009695399/basedefs/ctype.h.html). Note that this is not automatically generated, and may omit some types/functions from the original C header." I'm thinking we should actually just put a /// before every symbol, to get it in the ddoc so you can see what *is* included. Thoughts? I can put together a pull for core.stdc.* if it makes sense.
Blurb LGTM, please make it happen. Also let's experiment with the ///'s. If we get real cocky we might insert for each symbol a LUCKY link googling for the header name and symbol name. Thanks! -- Andrei
Jan 08 2015
next sibling parent reply Steven Schveighoffer <schveiguy yahoo.com> writes:
On 1/8/15 10:41 AM, Andrei Alexandrescu wrote:
 On 1/8/15 4:18 AM, Steven Schveighoffer wrote:
 Thoughts? I can put together a pull for core.stdc.* if it makes sense.
Blurb LGTM, please make it happen. Also let's experiment with the ///'s.
Just to put a semaphore on this, I'm partway through doing this, please don't someone else do it too, it's tedious work :) A couple of questions though: core.stdc.config is not technically a standard C header, and it seems pretty strange. I'm going to leave that one alone unless someone objects. There are many cases where the members are dependent on the OS. The one that strikes me as the most OS dependent (so far) is errno.d. I'm guessing that only one of those docs is going to go into the online docs? Is there a standard way to make them all show up (with nice categories to show which OS they apply to) which is not painful? If not, then we really need a good way to solve this... An idea might be to make a switch that tells the compiler to override it's internal predefinitions (e.g. compile with -DWin32 on Linux) just for doc generation, and have the resulting page have a way to "flavor" the page based on the OS you select or browse from. -Steve
Jan 08 2015
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/8/15 1:01 PM, Steven Schveighoffer wrote:
 There are many cases where the members are dependent on the OS. The one
 that strikes me as the most OS dependent (so far) is errno.d. I'm
 guessing that only one of those docs is going to go into the online
 docs? Is there a standard way to make them all show up (with nice
 categories to show which OS they apply to) which is not painful?

 If not, then we really need a good way to solve this... An idea might be
 to make a switch that tells the compiler to override it's internal
 predefinitions (e.g. compile with -DWin32 on Linux) just for doc
 generation, and have the resulting page have a way to "flavor" the page
 based on the OS you select or browse from.
I don't think there is a way. Making ddoc "cross-compilation" work would be an interesting project, but one of a lower priority. -- Andrei
Jan 08 2015
next sibling parent reply "Adam D. Ruppe" <destructionator gmail.com> writes:
On Thursday, 8 January 2015 at 21:14:43 UTC, Andrei Alexandrescu 
wrote:
 I don't think there is a way.
version(Ddoc) dummy prototypes maybe. But that gets painful. Though I think the compiler should NOT do conditional compilation when generating documentation. Instead, I'd prefer to just put it all out and then maybe group. So the doc would actually list the separate entries under all version headers. Not just OS, but arch or custom bits too. Then the user can see it all. Then by attaching classes to the outputted data you could easily do a filter by OS.
Jan 08 2015
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/8/15 1:23 PM, Adam D. Ruppe wrote:
 On Thursday, 8 January 2015 at 21:14:43 UTC, Andrei Alexandrescu wrote:
 I don't think there is a way.
version(Ddoc) dummy prototypes maybe. But that gets painful.
In doc builds we can probably define Windows on Linux etc.
 Though I think the compiler should NOT do conditional compilation when
 generating documentation. Instead, I'd prefer to just put it all out and
 then maybe group.

 So the doc would actually list the separate entries under all version
 headers. Not just OS, but arch or custom bits too. Then the user can see
 it all. Then by attaching classes to the outputted data you could easily
 do a filter by OS.
Yah, as I said it's a project. Andrei
Jan 08 2015
parent Jacob Carlborg <doob me.com> writes:
On 2015-01-08 22:25, Andrei Alexandrescu wrote:

 Yah, as I said it's a project.
Can we at least generate the documentation on multiple platforms, just to make sure we got all modules. -- /Jacob Carlborg
Jan 08 2015
prev sibling parent Jacob Carlborg <doob me.com> writes:
On 2015-01-08 22:23, Adam D. Ruppe wrote:
 On Thursday, 8 January 2015 at 21:14:43 UTC, Andrei Alexandrescu wrote:
 I don't think there is a way.
version(Ddoc) dummy prototypes maybe. But that gets painful.
Tango is using this method quite heavily in some modules. It also gives the opportunity to simplify signatures.
 Though I think the compiler should NOT do conditional compilation when
 generating documentation. Instead, I'd prefer to just put it all out and
 then maybe group.

 So the doc would actually list the separate entries under all version
 headers. Not just OS, but arch or custom bits too. Then the user can see
 it all. Then by attaching classes to the outputted data you could easily
 do a filter by OS.
That would be really nice. -- /Jacob Carlborg
Jan 08 2015
prev sibling parent "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Thu, Jan 08, 2015 at 01:14:43PM -0800, Andrei Alexandrescu via Digitalmars-d
wrote:
 On 1/8/15 1:01 PM, Steven Schveighoffer wrote:
There are many cases where the members are dependent on the OS. The
one that strikes me as the most OS dependent (so far) is errno.d. I'm
guessing that only one of those docs is going to go into the online
docs? Is there a standard way to make them all show up (with nice
categories to show which OS they apply to) which is not painful?

If not, then we really need a good way to solve this... An idea might
be to make a switch that tells the compiler to override it's internal
predefinitions (e.g. compile with -DWin32 on Linux) just for doc
generation, and have the resulting page have a way to "flavor" the
page based on the OS you select or browse from.
I don't think there is a way. Making ddoc "cross-compilation" work would be an interesting project, but one of a lower priority. --
[...] It's not just an "interesting" project; it's a pretty important one, seeing that the "std.windows.charset" link on dlang.org has been broken for a looooong time (probably *years*, by my estimation), just because dlang.org happens to be built on a Linux machine, so none of the Windows module make it into the ddoc pass (and even if they did, they'd be empty due to version(Windows) in the code). Not to mention the tons of other Windows-specific docs that will never make it to dlang.org for the same reason. It's a pretty nice way to turn off Windows users who are trying to find docs on dlang.org. :-P (I'm not a Windows user btw, so this doesn't really bother me in the least. But I'm sure you're probably a lot more concerned about the potential loss of users here.) T -- Heads I win, tails you lose.
Jan 08 2015
prev sibling next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2015-01-08 22:01, Steven Schveighoffer wrote:

 core.stdc.config is not technically a standard C header, and it seems
 pretty strange. I'm going to leave that one alone unless someone objects.
Shouldn't this then be documented like any other druntime/Phobos module.
 There are many cases where the members are dependent on the OS. The one
 that strikes me as the most OS dependent (so far) is errno.d. I'm
 guessing that only one of those docs is going to go into the online
 docs? Is there a standard way to make them all show up (with nice
 categories to show which OS they apply to) which is not painful?

 If not, then we really need a good way to solve this... An idea might be
 to make a switch that tells the compiler to override it's internal
 predefinitions (e.g. compile with -DWin32 on Linux) just for doc
 generation, and have the resulting page have a way to "flavor" the page
 based on the OS you select or browse from.
That would be cool. -- /Jacob Carlborg
Jan 08 2015
parent Steven Schveighoffer <schveiguy yahoo.com> writes:
On 1/9/15 2:14 AM, Jacob Carlborg wrote:
 On 2015-01-08 22:01, Steven Schveighoffer wrote:

 core.stdc.config is not technically a standard C header, and it seems
 pretty strange. I'm going to leave that one alone unless someone objects.
Shouldn't this then be documented like any other druntime/Phobos module.
Sure, that is fine by me. But I'm not going to do it, as I don't know what it's for :) -Steve
Jan 09 2015
prev sibling next sibling parent Walter Bright <newshound2 digitalmars.com> writes:
On 1/8/2015 1:01 PM, Steven Schveighoffer wrote:
 core.stdc.config is not technically a standard C header, and it seems pretty
 strange. I'm going to leave that one alone unless someone objects.
Yeah, the mere existence of that module grates.
Jan 08 2015
prev sibling parent Steven Schveighoffer <schveiguy yahoo.com> writes:
On 1/8/15 4:01 PM, Steven Schveighoffer wrote:
 On 1/8/15 10:41 AM, Andrei Alexandrescu wrote:
 On 1/8/15 4:18 AM, Steven Schveighoffer wrote:
 Thoughts? I can put together a pull for core.stdc.* if it makes sense.
Blurb LGTM, please make it happen. Also let's experiment with the ///'s.
Just to put a semaphore on this, I'm partway through doing this, please don't someone else do it too, it's tedious work :)
https://github.com/D-Programming-Language/druntime/pull/1091 -Steve
Jan 09 2015
prev sibling parent Walter Bright <newshound2 digitalmars.com> writes:
On 1/8/2015 7:41 AM, Andrei Alexandrescu wrote:
 If we get real cocky we might insert for each symbol a LUCKY link googling for
the
 header name and symbol name.
Livin' on the edge!
Jan 08 2015
prev sibling parent reply "Martin Nowak" <code dawg.eu> writes:
On Thursday, 8 January 2015 at 12:18:37 UTC, Steven Schveighoffer 
wrote:
 One thing that may be misleading about this -- our headers 
 don't include *everything* from C-land.
What's missing? They should just match their C counterparts.
Jan 09 2015
next sibling parent reply Steven Schveighoffer <schveiguy yahoo.com> writes:
On 1/9/15 12:08 PM, Martin Nowak wrote:
 On Thursday, 8 January 2015 at 12:18:37 UTC, Steven Schveighoffer wrote:
 One thing that may be misleading about this -- our headers don't
 include *everything* from C-land.
What's missing? They should just match their C counterparts.
Perhaps they do, I don't think we should guarantee it though. For instance, a macro may not be suited to be included in D because we have better options. -Steve
Jan 09 2015
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/9/15 10:10 AM, Steven Schveighoffer wrote:
 On 1/9/15 12:08 PM, Martin Nowak wrote:
 On Thursday, 8 January 2015 at 12:18:37 UTC, Steven Schveighoffer wrote:
 One thing that may be misleading about this -- our headers don't
 include *everything* from C-land.
What's missing? They should just match their C counterparts.
Perhaps they do, I don't think we should guarantee it though. For instance, a macro may not be suited to be included in D because we have better options.
Maybe Calypso could be used for that? -- Andrei
Jan 09 2015
parent Martin Nowak <code+news.digitalmars dawg.eu> writes:
On 01/09/2015 07:35 PM, Andrei Alexandrescu wrote:
 Maybe Calypso could be used for that? -- Andrei
What's calypso, can't find anything.
Jan 09 2015
prev sibling parent reply Steven Schveighoffer <schveiguy yahoo.com> writes:
On 1/9/15 12:08 PM, Martin Nowak wrote:
 On Thursday, 8 January 2015 at 12:18:37 UTC, Steven Schveighoffer wrote:
 One thing that may be misleading about this -- our headers don't
 include *everything* from C-land.
What's missing? They should just match their C counterparts.
Andrei had the idea to put the blurb in one place as a macro, so we can change it quite easily if you can think of a better statement. See here: https://github.com/D-Programming-Language/dlang.org/pull/752 -Steve
Jan 09 2015
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/9/15 10:46 AM, Steven Schveighoffer wrote:
 On 1/9/15 12:08 PM, Martin Nowak wrote:
 On Thursday, 8 January 2015 at 12:18:37 UTC, Steven Schveighoffer wrote:
 One thing that may be misleading about this -- our headers don't
 include *everything* from C-land.
What's missing? They should just match their C counterparts.
Andrei had the idea to put the blurb in one place as a macro, so we can change it quite easily if you can think of a better statement. See here: https://github.com/D-Programming-Language/dlang.org/pull/752
Stuff's up! http://dlang.org/library-prerelease/core/stdc/complex.html. I couldn't get rid of the darn space between the header name and the period. -- Andrei
Jan 09 2015
next sibling parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Fri, Jan 09, 2015 at 11:46:47AM -0800, Andrei Alexandrescu via Digitalmars-d
wrote:
[...]
 Stuff's up!
 http://dlang.org/library-prerelease/core/stdc/complex.html. I couldn't
 get rid of the darn space between the header name and the period.
[...] Isn't this caused by the fact that the various *REF*/*LINK* macros insert gratuitous &nbsp;'s after the link? I ran into this several times while rewriting std.algorithm docs, and it's very annoying, since it precludes using these macros in many places where I'd like to use them. I've had to rephrase sentences just so the extraneous spaces don't show up in the wrong place. T -- Programming is not just an act of telling a computer what to do: it is also an act of telling other programmers what you wished the computer to do. Both are important, and the latter deserves care. -- Andrew Morton
Jan 09 2015
next sibling parent reply "Tobias Pankrath" <tobias pankrath.net> writes:
On Friday, 9 January 2015 at 20:00:27 UTC, H. S. Teoh via 
Digitalmars-d wrote:
 On Fri, Jan 09, 2015 at 11:46:47AM -0800, Andrei Alexandrescu 
 via Digitalmars-d wrote:
 [...]
 Stuff's up!
 http://dlang.org/library-prerelease/core/stdc/complex.html. I 
 couldn't
 get rid of the darn space between the header name and the 
 period.
[...] Isn't this caused by the fact that the various *REF*/*LINK* macros insert gratuitous &nbsp;'s after the link? I ran into this several times while rewriting std.algorithm docs, and it's very annoying, since it precludes using these macros in many places where I'd like to use them. I've had to rephrase sentences just so the extraneous spaces don't show up in the wrong place. T
In this case there is a <span class="pln"> </span> that is 16px wide and occupies exactly the space you want to get rid of. It only shows up when viewing the HTML using the Chrome developer tools (F12). It's not in the page source.
Jan 09 2015
parent reply Martin Nowak <code+news.digitalmars dawg.eu> writes:
On 01/09/2015 09:29 PM, Tobias Pankrath wrote:
 In this case there is a <span class="pln"> </span> that is 16px wide and
 occupies exactly the space you want to get rid of. It only shows up when
 viewing the HTML using the Chrome developer tools (F12). It's not in the
 page source.
It's highlighted as D source.
Jan 09 2015
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/9/15 12:35 PM, Martin Nowak wrote:
 On 01/09/2015 09:29 PM, Tobias Pankrath wrote:
 In this case there is a <span class="pln"> </span> that is 16px wide and
 occupies exactly the space you want to get rid of. It only shows up when
 viewing the HTML using the Chrome developer tools (F12). It's not in the
 page source.
It's highlighted as D source.
Found Waldo. Please review. https://github.com/D-Programming-Language/dlang.org/pull/756 -- Andrei
Jan 09 2015
prev sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/9/15 11:58 AM, H. S. Teoh via Digitalmars-d wrote:
 On Fri, Jan 09, 2015 at 11:46:47AM -0800, Andrei Alexandrescu via
Digitalmars-d wrote:
 [...]
 Stuff's up!
 http://dlang.org/library-prerelease/core/stdc/complex.html. I couldn't
 get rid of the darn space between the header name and the period.
[...] Isn't this caused by the fact that the various *REF*/*LINK* macros insert gratuitous &nbsp;'s after the link?
No, I looked; I think it's because of the newline thereafter. -- Andrei
Jan 09 2015
prev sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2015-01-09 20:46, Andrei Alexandrescu wrote:

 Stuff's up! http://dlang.org/library-prerelease/core/stdc/complex.html.
 I couldn't get rid of the darn space between the header name and the
 period. -- Andrei
Is it just me or are the actual declarations missing? -- /Jacob Carlborg
Jan 09 2015
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/9/15 12:59 PM, Jacob Carlborg wrote:
 On 2015-01-09 20:46, Andrei Alexandrescu wrote:

 Stuff's up! http://dlang.org/library-prerelease/core/stdc/complex.html.
 I couldn't get rid of the darn space between the header name and the
 period. -- Andrei
Is it just me or are the actual declarations missing?
Oh yah :o). Steve? -- Andrei
Jan 09 2015
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/9/15 1:17 PM, Andrei Alexandrescu wrote:
 On 1/9/15 12:59 PM, Jacob Carlborg wrote:
 On 2015-01-09 20:46, Andrei Alexandrescu wrote:

 Stuff's up! http://dlang.org/library-prerelease/core/stdc/complex.html.
 I couldn't get rid of the darn space between the header name and the
 period. -- Andrei
Is it just me or are the actual declarations missing?
Oh yah :o). Steve? -- Andrei
http://dlang.org/library-prerelease/core/stdc/errno.html does list the enum values. -- Andrei
Jan 09 2015
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/9/15 1:18 PM, Andrei Alexandrescu wrote:
 On 1/9/15 1:17 PM, Andrei Alexandrescu wrote:
 On 1/9/15 12:59 PM, Jacob Carlborg wrote:
 On 2015-01-09 20:46, Andrei Alexandrescu wrote:

 Stuff's up! http://dlang.org/library-prerelease/core/stdc/complex.html.
 I couldn't get rid of the darn space between the header name and the
 period. -- Andrei
Is it just me or are the actual declarations missing?
Oh yah :o). Steve? -- Andrei
http://dlang.org/library-prerelease/core/stdc/errno.html does list the enum values. -- Andrei
... albeit wrongly: https://issues.dlang.org/show_bug.cgi?id=13961 -- Andrei
Jan 09 2015
prev sibling parent reply Steven Schveighoffer <schveiguy yahoo.com> writes:
On 1/9/15 4:17 PM, Andrei Alexandrescu wrote:
 On 1/9/15 12:59 PM, Jacob Carlborg wrote:
 On 2015-01-09 20:46, Andrei Alexandrescu wrote:

 Stuff's up! http://dlang.org/library-prerelease/core/stdc/complex.html.
 I couldn't get rid of the darn space between the header name and the
 period. -- Andrei
Is it just me or are the actual declarations missing?
Oh yah :o). Steve? -- Andrei
Apparently, the documentation generator ignores items that are tagged as documented but without any substance. If I compile a simple doc with a "///" before an item, it does show up when I do dmd -D. So I have no idea how to make it work for this new doc system. -Steve
Jan 11 2015
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/11/15 11:26 AM, Steven Schveighoffer wrote:
 On 1/9/15 4:17 PM, Andrei Alexandrescu wrote:
 On 1/9/15 12:59 PM, Jacob Carlborg wrote:
 On 2015-01-09 20:46, Andrei Alexandrescu wrote:

 Stuff's up! http://dlang.org/library-prerelease/core/stdc/complex.html.
 I couldn't get rid of the darn space between the header name and the
 period. -- Andrei
Is it just me or are the actual declarations missing?
Oh yah :o). Steve? -- Andrei
Apparently, the documentation generator ignores items that are tagged as documented but without any substance. If I compile a simple doc with a "///" before an item, it does show up when I do dmd -D. So I have no idea how to make it work for this new doc system.
Martin Nowak? Sönke Ludwig? Andrei
Jan 11 2015
parent "Mathias LANG" <geod24 gmail.com> writes:
On Sunday, 11 January 2015 at 19:52:42 UTC, Andrei Alexandrescu 
wrote:
 On 1/11/15 11:26 AM, Steven Schveighoffer wrote:
 On 1/9/15 4:17 PM, Andrei Alexandrescu wrote:
 On 1/9/15 12:59 PM, Jacob Carlborg wrote:
 On 2015-01-09 20:46, Andrei Alexandrescu wrote:

 Stuff's up! 
 http://dlang.org/library-prerelease/core/stdc/complex.html.
 I couldn't get rid of the darn space between the header 
 name and the
 period. -- Andrei
Is it just me or are the actual declarations missing?
Oh yah :o). Steve? -- Andrei
Apparently, the documentation generator ignores items that are tagged as documented but without any substance. If I compile a simple doc with a "///" before an item, it does show up when I do dmd -D. So I have no idea how to make it work for this new doc system.
Martin Nowak? Sönke Ludwig? Andrei
That's a feature, not a bug ! (tm) I think what's going on is that `--only-documented` is somehow specified. I had a glance at dlang.org and couldn't find the flag, but it's present by default if you build with dub, and I have no idea how Phobos' ddox are build ATM. `--only-documented` filters everything that have an empty comment out (https://github.com/rejectedsoftware/ddox/blob/master/source/ddox/main.d#L193). Which looks like a bug (or at least, something that has been overlooked), as dmd differentiate between empty comment and no comment.
Jan 11 2015
prev sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2015-01-07 00:44, weaselcat wrote:

 Is it intentional for all of the stdc pages to be empty?
Why is even std.c.* still available. These should all be replaced with core.stdc.*. -- /Jacob Carlborg
Jan 07 2015
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/7/15 1:06 AM, Jacob Carlborg wrote:
 On 2015-01-07 00:44, weaselcat wrote:

 Is it intentional for all of the stdc pages to be empty?
Why is even std.c.* still available. These should all be replaced with core.stdc.*.
Please fix or file so this isn't forgotten. -- Andrei
Jan 07 2015
parent Jacob Carlborg <doob me.com> writes:
On 2015-01-07 16:42, Andrei Alexandrescu wrote:

 Please fix or file so this isn't forgotten. -- Andrei
https://issues.dlang.org/show_bug.cgi?id=13948 Perhaps it should automatically ignore deprecated modules? -- /Jacob Carlborg
Jan 07 2015
prev sibling next sibling parent reply "Danny" <danny.milo+a gmail.com> writes:
http://dlang.org/library/core/math/ldexp.html

"Compute n * 2⊃"

Huh?
Jan 06 2015
parent reply "Brad Anderson" <eco gnuk.net> writes:
On Wednesday, 7 January 2015 at 00:06:28 UTC, Danny wrote:
 http://dlang.org/library/core/math/ldexp.html

 "Compute n * 2⊃"

 Huh?
Weird. It's `Compute n * 2$(SUP exp)` in the source[1]. SUP is a locally defined macro. Maybe ddox doesn't like local macros? 1. https://github.com/D-Programming-Language/druntime/blob/v2.066.1/src/core/math.d#L96
Jan 06 2015
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/6/15 4:42 PM, Brad Anderson wrote:
 On Wednesday, 7 January 2015 at 00:06:28 UTC, Danny wrote:
 http://dlang.org/library/core/math/ldexp.html

 "Compute n * 2⊃"

 Huh?
Weird. It's `Compute n * 2$(SUP exp)` in the source[1]. SUP is a locally defined macro. Maybe ddox doesn't like local macros? 1. https://github.com/D-Programming-Language/druntime/blob/v2.066.1/src/core/math.d#L96
Yah, looks like a problem with ddox. Anyhow for now I fixed by using SUPERSCRIPT. https://github.com/D-Programming-Language/druntime/commit/8f655bbdd8f7aa77907053c918d78d2286c93ab2 http://dlang.org/library-prerelease/core/math/ldexp.html Andrei
Jan 06 2015
prev sibling next sibling parent reply "Robert burner Schadek" <rburners gmail.com> writes:
std.string looks fine only the indexOfNeither and 
lastIndexOfNeither are missing
Jan 06 2015
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/6/15 4:26 PM, Robert burner Schadek wrote:
 std.string looks fine only the indexOfNeither and lastIndexOfNeither are
 missing
Could you please fix -- thanks! -- Andrei
Jan 06 2015
parent "Robert burner Schadek" <rburners gmail.com> writes:
On Wednesday, 7 January 2015 at 01:13:21 UTC, Andrei Alexandrescu 
wrote:
 On 1/6/15 4:26 PM, Robert burner Schadek wrote:
 std.string looks fine only the indexOfNeither and 
 lastIndexOfNeither are
 missing
Could you please fix -- thanks! -- Andrei
I think I just did. Does the webpage show 2.066? If so indexOfNeither must not be part as it was merged after the release.
Jan 07 2015
prev sibling next sibling parent reply Steven Schveighoffer <schveiguy yahoo.com> writes:
On 1/6/15 5:43 PM, Andrei Alexandrescu wrote:
 Let's crowdsource the review. Please check the entries linked from here:
 http://dlang.org/library/index.html.
std.algorithm has many of the "descriptions" showing samples. Also, I know the table at the top is to make things easier for standard ddoc, should that be removed? BTW, I'm all for the docs to be switched. Just the cross-referencing alone is worth it. -Steve
Jan 06 2015
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/6/15 6:17 PM, Steven Schveighoffer wrote:
 On 1/6/15 5:43 PM, Andrei Alexandrescu wrote:
 Let's crowdsource the review. Please check the entries linked from here:
 http://dlang.org/library/index.html.
std.algorithm has many of the "descriptions" showing samples. Also, I know the table at the top is to make things easier for standard ddoc, should that be removed?
But I like it.
 BTW, I'm all for the docs to be switched. Just the cross-referencing
 alone is worth it.
One thing we need to do is offer for each module "view as one page" so people still have that option. Andrei
Jan 06 2015
parent Steven Schveighoffer <schveiguy yahoo.com> writes:
On 1/7/15 1:03 AM, Andrei Alexandrescu wrote:
 On 1/6/15 6:17 PM, Steven Schveighoffer wrote:
 On 1/6/15 5:43 PM, Andrei Alexandrescu wrote:
 Let's crowdsource the review. Please check the entries linked from here:
 http://dlang.org/library/index.html.
std.algorithm has many of the "descriptions" showing samples. Also, I know the table at the top is to make things easier for standard ddoc, should that be removed?
But I like it.
It's redundant. Right below is the same exact info (see "Cheat sheet").
 BTW, I'm all for the docs to be switched. Just the cross-referencing
 alone is worth it.
One thing we need to do is offer for each module "view as one page" so people still have that option.
That would be nice. In fact, I would recommend for when javascript is enabled, a way to "expand" a function/class inline. -Steve
Jan 08 2015
prev sibling next sibling parent Walter Bright <newshound2 digitalmars.com> writes:
On 1/6/2015 2:43 PM, Andrei Alexandrescu wrote:
 Let's crowdsource the review. Please check the entries linked from here:
 http://dlang.org/library/index.html.
Looks nice! And will provide motivation to fix a lot of the under-documented functions.
Jan 06 2015
prev sibling next sibling parent Walter Bright <newshound2 digitalmars.com> writes:
On 1/6/2015 2:43 PM, Andrei Alexandrescu wrote:
 Let's crowdsource the review. Please check the entries linked from here:
 http://dlang.org/library/index.html.
In: http://dlang.org/library/std/algorithm/make_index.html if you click on the 'forward' link, it takes you to something quite unexpected. Looks like an issue with automatic cross referencing?
Jan 06 2015
prev sibling next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 1/6/2015 2:43 PM, Andrei Alexandrescu wrote:
 Let's crowdsource the review. Please check the entries linked from here:
 http://dlang.org/library/index.html.
The table: got lost: http://dlang.org/library/std/math/cos.html Also, the 2$(SUP 64). got turned into 2,64.
Jan 06 2015
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/6/15 7:20 PM, Walter Bright wrote:
 On 1/6/2015 2:43 PM, Andrei Alexandrescu wrote:
 Let's crowdsource the review. Please check the entries linked from here:
 http://dlang.org/library/index.html.
The table: got lost: http://dlang.org/library/std/math/cos.html Also, the 2$(SUP 64). got turned into 2,64.
https://github.com/D-Programming-Language/phobos/commit/7e766e6796a494de5a55c11d106889b47c303eff Andrei
Jan 06 2015
prev sibling next sibling parent reply Paul O'Neil <redballoon36 gmail.com> writes:
On 01/06/2015 05:43 PM, Andrei Alexandrescu wrote:
 Let's crowdsource the review. Please check the entries linked from here:
 http://dlang.org/library/index.html.
 
 Andrei
On that page itself, the descriptions for at least std.regex and std.uni include the headers (e.g Intro, Overview) from those pages. -- Paul O'Neil Github / IRC: todayman
Jan 06 2015
next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/6/15 7:27 PM, Paul O'Neil wrote:
 On 01/06/2015 05:43 PM, Andrei Alexandrescu wrote:
 Let's crowdsource the review. Please check the entries linked from here:
 http://dlang.org/library/index.html.

 Andrei
On that page itself, the descriptions for at least std.regex and std.uni include the headers (e.g Intro, Overview) from those pages.
Thanks! -- Andrei
Jan 06 2015
prev sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/6/15 7:27 PM, Paul O'Neil wrote:
 On 01/06/2015 05:43 PM, Andrei Alexandrescu wrote:
 Let's crowdsource the review. Please check the entries linked from here:
 http://dlang.org/library/index.html.

 Andrei
On that page itself, the descriptions for at least std.regex and std.uni include the headers (e.g Intro, Overview) from those pages.
Fixed in http://dlang.org/library-prerelease/index.html. -- Andrei
Jan 06 2015
prev sibling next sibling parent reply Manu via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 7 January 2015 at 08:43, Andrei Alexandrescu via Digitalmars-d
<digitalmars-d puremagic.com> wrote:
 Let's crowdsource the review. Please check the entries linked from here:
 http://dlang.org/library/index.html.

 Andrei
Very first function I looked at: http://dlang.org/library/std/string/format.html I find all the horizontal bar's throughout the docs quite noisy and tiring, and somewhat antiquated stylistically. I expected the parameters to jump out at me, but I didn't notice that that block surrounded by black lines and bold headings was actually the parameter list. I don't think I need headings to tell me which column is the name and which is the description. Ie, the parameters didn't jump out at me, the noise surrounding them did, and distracted me from the parameters themselves. There's obviously a bug here where the text is red too. My suggestions to make that page look more professional: * Prototype needs proper syntax highlighting, and elements (builtin types, types, template args, runtime args, and the function name itself) need to be styled distinctly (and tastefully). * The noise around the parameter listing can be removed completely. * The parameter name string in the parameter listing should match the styling of the prototype, so you can immediately recognise the thing in the prototype's description on the page. * The coloured box that houses the prototype is 6 times wider than it needs to be (on my monitor). I think it should be horizontally sized to fit the content. * Authors, license, and other uninteresting information should be spaced from the content (give an extra line-break or 2), and also the text should be significantly smaller. This is, literally, the fine-print. Comment box at the bottom is awesome! Taking another random sample: http://dlang.org/library/std/csv.html My previous criticisms stand equally. I feel like 'see also' should be the last thing before the 'fine print', not the first thing. Clicking through to see a class: http://dlang.org/library/std/csv/csv_exception.html Prior criticisms apply, but looks okay otherwise. There is 'fields' and 'methods', but they look the same. This is unexpected, since methods are functions, with return types, and arguments... why can't I see those? I'll leave it there for a moment. How do we style this stuff? Is there some way that we can experiment with styling ourselves?
Jan 06 2015
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/6/15 8:54 PM, Manu via Digitalmars-d wrote:
 On 7 January 2015 at 08:43, Andrei Alexandrescu via Digitalmars-d
 <digitalmars-d puremagic.com> wrote:
 Let's crowdsource the review. Please check the entries linked from here:
 http://dlang.org/library/index.html.

 Andrei
Very first function I looked at: http://dlang.org/library/std/string/format.html I find all the horizontal bar's throughout the docs quite noisy and tiring, and somewhat antiquated stylistically.
FWIW the table styling is the least problem with that page. Apparently the indexer messes up things quite a lot, making text red when it shouldn't and not rendering code correctly etc.
 I expected the parameters to jump out at me, but I didn't notice that
 that block surrounded by black lines and bold headings was actually
 the parameter list. I don't think I need headings to tell me which
 column is the name and which is the description. Ie, the parameters
 didn't jump out at me, the noise surrounding them did, and distracted
 me from the parameters themselves.
So Name/Description should go? Also parameters should be in code font.
 There's obviously a bug here where the text is red too.
Yah that's a biggie. Notice the code snippets that were supposed to be syntax colored too... Looks like that's a problem in the source. This looks just as bad:
 My suggestions to make that page look more professional:

 * Prototype needs proper syntax highlighting, and elements (builtin
 types, types, template args, runtime args, and the function name
 itself) need to be styled distinctly (and tastefully).
 * The noise around the parameter listing can be removed completely.
 * The parameter name string in the parameter listing should match the
 styling of the prototype, so you can immediately recognise the thing
 in the prototype's description on the page.
 * The coloured box that houses the prototype is 6 times wider than it
 needs to be (on my monitor). I think it should be horizontally sized
 to fit the content.
 * Authors, license, and other uninteresting information should be
 spaced from the content (give an extra line-break or 2), and also the
 text should be significantly smaller. This is, literally, the
 fine-print.
Noice.
 Comment box at the bottom is awesome!

 Taking another random sample: http://dlang.org/library/std/csv.html

 My previous criticisms stand equally.
 I feel like 'see also' should be the last thing before the 'fine
 print', not the first thing.

 Clicking through to see a class:
 http://dlang.org/library/std/csv/csv_exception.html

 Prior criticisms apply, but looks okay otherwise.
 There is 'fields' and 'methods', but they look the same. This is
 unexpected, since methods are functions, with return types, and
 arguments... why can't I see those?

 I'll leave it there for a moment.


 How do we style this stuff? Is there some way that we can experiment
 with styling ourselves?
Mainly css, see https://github.com/D-Programming-Language/dlang.org/tree/master/css. Some styling in the html.ddoc and other .ddoc files, see https://github.com/D-Programming-Language/dlang.org/tree/master/. Andrei
Jan 06 2015
prev sibling next sibling parent ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Tue, 06 Jan 2015 14:43:45 -0800
Andrei Alexandrescu via Digitalmars-d <digitalmars-d puremagic.com>
wrote:

 Let's crowdsource the review. Please check the entries linked from here:=
=20
 http://dlang.org/library/index.html.
so looking at the function documentation i lost that nice indexes. if i got to the function directly (which will be very likely with googling), now i have to either drop keyboard and use mouse to click on module name (which is not immideately pops like a link, btw), possibly scrolling the page to top, or try to use keyboard navigation, which has only one thing in common for various browsers: it's awful. on the previous version it was not only enough to press "home" and see that, i was able to start quicksearching for other functions and read all the documentation without reloading the page (now two pages, actually). i don't know about others, but for me new version is like a modern smartphone: shiny, cool, looking pretty and making phone talks worser.
Jan 06 2015
prev sibling next sibling parent reply Manu via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 7 January 2015 at 08:43, Andrei Alexandrescu via Digitalmars-d
<digitalmars-d puremagic.com> wrote:
 Let's crowdsource the review. Please check the entries linked from here:
 http://dlang.org/library/index.html.

 Andrei
Another one; I tried to use the search box on the top right corner... it just resulted in a google search. Can we do better than that? When people go to the documentation page, they want to search the docs, not get a standard google results page.
Jan 06 2015
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/6/15 10:09 PM, Manu via Digitalmars-d wrote:
 On 7 January 2015 at 08:43, Andrei Alexandrescu via Digitalmars-d
 <digitalmars-d puremagic.com> wrote:
 Let's crowdsource the review. Please check the entries linked from here:
 http://dlang.org/library/index.html.

 Andrei
Another one; I tried to use the search box on the top right corner... it just resulted in a google search. Can we do better than that? When people go to the documentation page, they want to search the docs, not get a standard google results page.
That would be quite an involved project. -- Andrei
Jan 06 2015
next sibling parent reply "Mathias LANG" <geod24 gmail.com> writes:
On Wednesday, 7 January 2015 at 06:48:23 UTC, Andrei Alexandrescu
wrote:
 On 1/6/15 10:09 PM, Manu via Digitalmars-d wrote:
 On 7 January 2015 at 08:43, Andrei Alexandrescu via 
 Digitalmars-d
 <digitalmars-d puremagic.com> wrote:
 Let's crowdsource the review. Please check the entries linked 
 from here:
 http://dlang.org/library/index.html.

 Andrei
Another one; I tried to use the search box on the top right corner... it just resulted in a google search. Can we do better than that? When people go to the documentation page, they want to search the docs, not get a standard google results page.
That would be quite an involved project. -- Andrei
I don't think so, since vibed.org has exactly that. I'm not familiar with JS, but I believe https://github.com/rejectedsoftware/vibed.org/blob/master/public/scripts/ddox.js could be a good starter place.
Jan 06 2015
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/6/15 11:02 PM, Mathias LANG wrote:
 On Wednesday, 7 January 2015 at 06:48:23 UTC, Andrei Alexandrescu
 wrote:
 On 1/6/15 10:09 PM, Manu via Digitalmars-d wrote:
 On 7 January 2015 at 08:43, Andrei Alexandrescu via Digitalmars-d
 <digitalmars-d puremagic.com> wrote:
 Let's crowdsource the review. Please check the entries linked from
 here:
 http://dlang.org/library/index.html.

 Andrei
Another one; I tried to use the search box on the top right corner... it just resulted in a google search. Can we do better than that? When people go to the documentation page, they want to search the docs, not get a standard google results page.
That would be quite an involved project. -- Andrei
I don't think so, since vibed.org has exactly that. I'm not familiar with JS, but I believe https://github.com/rejectedsoftware/vibed.org/blob/master/public/scripts/ddox.js could be a good starter place.
Oh, nice. I would, however, hope we fix the many more pressing issues with dub right now. For starters, I have no idea how to fix http://dlang.org/library-prerelease/std/string/format.html in spite of having operated this: https://github.com/D-Programming-Language/phobos/commit/e03e647cea5a2cff0ff72195e8c7907127b3b5e6. How does documentation in std.format make it in std.string's documentation? Andrei
Jan 06 2015
parent "Mathias LANG" <geod24 gmail.com> writes:
On Wednesday, 7 January 2015 at 07:06:42 UTC, Andrei Alexandrescu 
wrote:
 On 1/6/15 11:02 PM, Mathias LANG wrote:
 On Wednesday, 7 January 2015 at 06:48:23 UTC, Andrei 
 Alexandrescu
 wrote:
 On 1/6/15 10:09 PM, Manu via Digitalmars-d wrote:
 On 7 January 2015 at 08:43, Andrei Alexandrescu via 
 Digitalmars-d
 <digitalmars-d puremagic.com> wrote:
 Let's crowdsource the review. Please check the entries 
 linked from
 here:
 http://dlang.org/library/index.html.

 Andrei
Another one; I tried to use the search box on the top right corner... it just resulted in a google search. Can we do better than that? When people go to the documentation page, they want to search the docs, not get a standard google results page.
That would be quite an involved project. -- Andrei
I don't think so, since vibed.org has exactly that. I'm not familiar with JS, but I believe https://github.com/rejectedsoftware/vibed.org/blob/master/public/scripts/ddox.js could be a good starter place.
Oh, nice. I would, however, hope we fix the many more pressing issues with dub right now. For starters, I have no idea how to fix http://dlang.org/library-prerelease/std/string/format.html in spite of having operated this: https://github.com/D-Programming-Language/phobos/commit/e03e647cea5a2cff0ff72195e8c7907127b3b5e6. How does documentation in std.format make it in std.string's documentation? Andrei
That's funny. Looks like symbol publicly imported are generated (but not indexed). For example, icmp is there as well.
Jan 06 2015
prev sibling next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 1/6/2015 10:48 PM, Andrei Alexandrescu wrote:
 Another one; I tried to use the search box on the top right corner...
 it just resulted in a google search.
 Can we do better than that? When people go to the documentation page,
 they want to search the docs, not get a standard google results page.
That would be quite an involved project. -- Andrei
I find dman.exe to be very handy and use it all the time, but since it is a hand-built index, it is always hopelessly out of date.
Jan 06 2015
parent reply "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Wednesday, 7 January 2015 at 07:12:33 UTC, Walter Bright wrote:
 On 1/6/2015 10:48 PM, Andrei Alexandrescu wrote:
 Another one; I tried to use the search box on the top right 
 corner...
 it just resulted in a google search.
 Can we do better than that? When people go to the 
 documentation page,
 they want to search the docs, not get a standard google 
 results page.
That would be quite an involved project. -- Andrei
I find dman.exe to be very handy and use it all the time, but since it is a hand-built index, it is always hopelessly out of date.
Why not reuse the index built by chmgen? It's very inclusive and mostly accurate.
Jan 07 2015
parent Walter Bright <newshound2 digitalmars.com> writes:
On 1/7/2015 12:41 AM, Vladimir Panteleev wrote:
 On Wednesday, 7 January 2015 at 07:12:33 UTC, Walter Bright wrote:
 I find dman.exe to be very handy and use it all the time, but since it is a
 hand-built index, it is always hopelessly out of date.
Why not reuse the index built by chmgen? It's very inclusive and mostly accurate.
There seems to be a lack of documentation on it :-( Anyhow, dman is pretty simple. It maps the command line argument to a url and opens the browser on the url. If the argument is not in its index, it reverts to using google. It would be much improved if it were combined with chmgen somehow.
Jan 07 2015
prev sibling parent "Adam D. Ruppe" <destructionator gmail.com> writes:
On Wednesday, 7 January 2015 at 06:48:23 UTC, Andrei Alexandrescu 
wrote:
 That would be quite an involved project. -- Andrei
http://dpldocs.info/
Jan 07 2015
prev sibling next sibling parent reply Manu via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 7 January 2015 at 08:43, Andrei Alexandrescu via Digitalmars-d
<digitalmars-d puremagic.com> wrote:
 Let's crowdsource the review. Please check the entries linked from here:
 http://dlang.org/library/index.html.

 Andrei
Another thought, since per-page docs result in a lot more page loads, this page *really* needs to be populated by ajax requests. It's wasteful to reload the whole page on every click. I'm in Australia, we don't really have internet in this country anymore! Is there a server that serves the raw data for the docs? It would be ideal for the client to format the page. We don't need to be sending HTML around.
Jan 06 2015
parent Rikki Cattermole <alphaglosined gmail.com> writes:
On 7/01/2015 7:20 p.m., Manu via Digitalmars-d wrote:
 On 7 January 2015 at 08:43, Andrei Alexandrescu via Digitalmars-d
 <digitalmars-d puremagic.com> wrote:
 Let's crowdsource the review. Please check the entries linked from here:
 http://dlang.org/library/index.html.

 Andrei
Another thought, since per-page docs result in a lot more page loads, this page *really* needs to be populated by ajax requests. It's wasteful to reload the whole page on every click. I'm in Australia, we don't really have internet in this country anymore! Is there a server that serves the raw data for the docs? It would be ideal for the client to format the page. We don't need to be sending HTML around.
I was thinking a little similarly. But using DDOC to generate JSON. Serve that from web server. Something like https://github.com/rikkimax/client-templating could be used to fill out based upon the data via widgets. Of course then it won't be prefilled when served but meh. Think Facebook's Big Pipe only more open.
Jan 06 2015
prev sibling next sibling parent "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Wed, Jan 07, 2015 at 07:44:39AM +0200, ketmar via Digitalmars-d wrote:
 On Tue, 06 Jan 2015 14:43:45 -0800
 Andrei Alexandrescu via Digitalmars-d <digitalmars-d puremagic.com>
 wrote:
 
 Let's crowdsource the review. Please check the entries linked from
 here: http://dlang.org/library/index.html.
so looking at the function documentation i lost that nice indexes. if i got to the function directly (which will be very likely with googling), now i have to either drop keyboard and use mouse to click on module name (which is not immideately pops like a link, btw), possibly scrolling the page to top, or try to use keyboard navigation, which has only one thing in common for various browsers: it's awful.
[...] You should use Vimperator. :-P I started using it recently, didn't like it that much at first, but I'm starting to like it more and more. Thanks to the hinting system, my rodent is even more out-of-use nowadays, which I consider a Good Thing(tm). T -- LINUX = Lousy Interface for Nefarious Unix Xenophobes.
Jan 06 2015
prev sibling next sibling parent ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Tue, 6 Jan 2015 22:32:05 -0800
"H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> wrote:

 On Wed, Jan 07, 2015 at 07:44:39AM +0200, ketmar via Digitalmars-d wrote:
 On Tue, 06 Jan 2015 14:43:45 -0800
 Andrei Alexandrescu via Digitalmars-d <digitalmars-d puremagic.com>
 wrote:
=20
 Let's crowdsource the review. Please check the entries linked from
 here: http://dlang.org/library/index.html.
so looking at the function documentation i lost that nice indexes. if i got to the function directly (which will be very likely with googling), now i have to either drop keyboard and use mouse to click on module name (which is not immideately pops like a link, btw), possibly scrolling the page to top, or try to use keyboard navigation, which has only one thing in common for various browsers: it's awful.
[...] =20 You should use Vimperator. :-P I started using it recently, didn't like it that much at first, but I'm starting to like it more and more. Thanks to the hinting system, my rodent is even more out-of-use nowadays, which I consider a Good Thing(tm).
sadly, there is no such thing for Opera 12. T_T
Jan 06 2015
prev sibling next sibling parent reply "Tobias Pankrath" <tobias pankrath.net> writes:
On Tuesday, 6 January 2015 at 22:43:45 UTC, Andrei Alexandrescu 
wrote:
 Let's crowdsource the review. Please check the entries linked 
 from here: http://dlang.org/library/index.html.

 Andrei
Has it been generated from an up-to-date version? Where are the sub modules of std.container? http://dlang.org/library/std/container.html
Jan 07 2015
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/7/15 12:22 AM, Tobias Pankrath wrote:
 On Tuesday, 6 January 2015 at 22:43:45 UTC, Andrei Alexandrescu wrote:
 Let's crowdsource the review. Please check the entries linked from
 here: http://dlang.org/library/index.html.

 Andrei
Has it been generated from an up-to-date version? Where are the sub modules of std.container? http://dlang.org/library/std/container.html
Try http://dlang.org/library-prerelease/std/container.html -- Andrei
Jan 07 2015
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/7/15 12:24 AM, Andrei Alexandrescu wrote:
 On 1/7/15 12:22 AM, Tobias Pankrath wrote:
 On Tuesday, 6 January 2015 at 22:43:45 UTC, Andrei Alexandrescu wrote:
 Let's crowdsource the review. Please check the entries linked from
 here: http://dlang.org/library/index.html.

 Andrei
Has it been generated from an up-to-date version? Where are the sub modules of std.container? http://dlang.org/library/std/container.html
Try http://dlang.org/library-prerelease/std/container.html -- Andrei
Apparently the links exist, but don't work, e.g. http://dlang.org/library-prerelease/std/std_container_array is not to be found. -- Andrei
Jan 07 2015
parent "Tobias Pankrath" <tobias pankrath.net> writes:
 Apparently the links exist, but don't work, e.g. 
 http://dlang.org/library-prerelease/std/std_container_array is 
 not to be found. -- Andrei
It works from the tree on the left.
Jan 07 2015
prev sibling next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/6/15 2:43 PM, Andrei Alexandrescu wrote:
 Let's crowdsource the review. Please check the entries linked from here:
 http://dlang.org/library/index.html.
Many thanks to those who provided feedback on the new layout! I've fixed a few issues, but it looks like there are quite a few more problems than I had anticipated. I encourage any and all of you to build the documentation locally (make -j should work nicely) and help with pull requests to github. Let's get this off the ground together. Thanks, Andrei
Jan 07 2015
prev sibling next sibling parent reply "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Tuesday, 6 January 2015 at 22:43:45 UTC, Andrei Alexandrescu 
wrote:
 Let's crowdsource the review. Please check the entries linked 
 from here: http://dlang.org/library/index.html.
From my last complain thread: http://forum.dlang.org/post/zazgfoxjwhjbdrgdiiqv forum.dlang.org I see that many of the issues with my example got fixed. Remaining issues: * Overzealous linking of words in the documentation that happen to coincide with symbols in the same module. This should only be done for text in $(D ...) tags. * Compile-time expressions are expanded to their computed variant. For example, `size_t.max` is expanded to `18446744073709551615LU`, which is not informative, and wrong on 32-bit systems. `Config.none` is now `cast(Config)0`, which sucks. I guess this is a compiler issue rather than a DDox one. More issues I noticed now from a quick look: * http://dlang.org/library/std/process.html : The comparison table is gone, replaced with an unstructured blob of text. * http://dlang.org/library/std/parallelism.html : More overzealous linking (e.g.: "These include _parallel_ foreach, _parallel_ reduce, _parallel_ eager map, ..."). * http://dlang.org/library/core/time.html : More overzealous linking - symbols within D string literals should not be linked. * I still have reservations about using Disqus.
Jan 07 2015
next sibling parent "Mathias LANG" <geod24 gmail.com> writes:
On Wednesday, 7 January 2015 at 08:46:41 UTC, Vladimir Panteleev 
wrote:
 * Overzealous linking of words in the documentation that happen 
 to coincide with symbols in the same module. This should only 
 be done for text in $(D ...) tags.
According to the specs: Identifiers in documentation comments that are function parameters or are names that are in scope at the associated declaration are emphasized in the output. This emphasis can take the form of italics, boldface, a hyperlink, etc. How it is emphasized depends on what it is - a function parameter, type, D keyword, etc. To prevent unintended emphasis of an identifier, it can be preceded by an underscore (_). The underscore will be stripped from the output. So it's conforming. However, I think this specific part of the spec cause more problems than it solves. Just think about using `any`, `all`, `find` and so on in `std.algorithm. Maybe it's time to update the specs ? :)
Jan 07 2015
prev sibling next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/7/15 12:46 AM, Vladimir Panteleev wrote:
 Remaining issues:

 * Overzealous linking of words in the documentation that happen to
 coincide with symbols in the same module. This should only be done for
 text in $(D ...) tags.
Yah, I'm quite unhappy about that, too.
 * Compile-time expressions are expanded to their computed variant. For
 example, `size_t.max` is expanded to `18446744073709551615LU`, which is
 not informative, and wrong on 32-bit systems. `Config.none` is now
 `cast(Config)0`, which sucks. I guess this is a compiler issue rather
 than a DDox one.
Hrm, not sure how easy it would be to fix this.
 More issues I noticed now from a quick look:

 * http://dlang.org/library/std/process.html :

    The comparison table is gone, replaced with an unstructured blob of
 text.

 * http://dlang.org/library/std/parallelism.html :

    More overzealous linking (e.g.: "These include _parallel_ foreach,
 _parallel_ reduce, _parallel_ eager map, ...").

 * http://dlang.org/library/core/time.html :

    More overzealous linking - symbols within D string literals should
 not be linked.
Could you please fix or file these. Thanks!
 * I still have reservations about using Disqus.
I did keep that in mind. The long and short of it it it's impossible to make a change that everybody likes. We must move forward. Andrei
Jan 07 2015
parent reply "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Wednesday, 7 January 2015 at 15:42:24 UTC, Andrei Alexandrescu 
wrote:
 Could you please fix or file these. Thanks!
The D or DDox issue tracker?
 * I still have reservations about using Disqus.
I did keep that in mind. The long and short of it it it's impossible to make a change that everybody likes. We must move forward.
I agree, it might very well be the least of all evils.
Jan 07 2015
next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/7/15 7:55 AM, Vladimir Panteleev wrote:
 On Wednesday, 7 January 2015 at 15:42:24 UTC, Andrei Alexandrescu wrote:
 Could you please fix or file these. Thanks!
The D or DDox issue tracker?
Either, appropriately :o). -- Andrei
Jan 07 2015
prev sibling parent reply Steven Schveighoffer <schveiguy yahoo.com> writes:
On 1/7/15 10:55 AM, Vladimir Panteleev wrote:
 On Wednesday, 7 January 2015 at 15:42:24 UTC, Andrei Alexandrescu wrote:
 * I still have reservations about using Disqus.
I did keep that in mind. The long and short of it it it's impossible to make a change that everybody likes. We must move forward.
I agree, it might very well be the least of all evils.
Just a thought on this -- from personal experience I like disqus quite a lot for commenting on fleeting topics, such as blog posts or articles. But these are quite static pages. However, I've benefited greatly from e.g. php doc comments which show ways to solve problems I am trying to solve. So I think we should keep these for that purpose. We have several issues to consider with disqus (or any commenting system): Inevitably, questions about the docs will be asked. If nobody looks at the docs (and let's face it, most of our veterans do not look at the docs every day), then the perception is that nobody is listening. Can we at least forward the posts to a NG/mailing list? I doubt such questions would happen frequently. I think anyone who has commit rights to any D project should be made moderator so they can stomp out trolls, remove fleeting/simple questions (after nudging towards d.learn), etc. There is going to be a push at some point to split up docs (e.g. std.datetime), is it possible to move a disqus comment from one page to another? -Steve
Jan 08 2015
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/8/15 4:31 AM, Steven Schveighoffer wrote:
 I think anyone who has commit rights to any D project should be made
 moderator so they can stomp out trolls, remove fleeting/simple questions
 (after nudging towards d.learn), etc.
Sönke could do this I think. -- Andrei
Jan 08 2015
prev sibling parent "Martin Nowak" <code dawg.eu> writes:
On Wednesday, 7 January 2015 at 08:46:41 UTC, Vladimir Panteleev 
wrote:
 * I still have reservations about using Disqus.
I'm quite happy with the self hosted isso comments on my blog. https://code.dawg.eu/reducing-vibed-turnaround-time-part-2-less-compiling.html#isso-thread
Jan 09 2015
prev sibling next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2015-01-06 23:43, Andrei Alexandrescu wrote:
 Let's crowdsource the review. Please check the entries linked from here:
 http://dlang.org/library/index.html.
What about all those suggestions in the thread "Improving ddoc" [1]? Some of those suggestions might require to redesign the documentation. Is it still worth updating to the new layout? [1] http://forum.dlang.org/thread/m81k2p$k47$1 digitalmars.com -- /Jacob Carlborg
Jan 07 2015
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/7/15 1:14 AM, Jacob Carlborg wrote:
 On 2015-01-06 23:43, Andrei Alexandrescu wrote:
 Let's crowdsource the review. Please check the entries linked from here:
 http://dlang.org/library/index.html.
What about all those suggestions in the thread "Improving ddoc" [1]? Some of those suggestions might require to redesign the documentation. Is it still worth updating to the new layout? [1] http://forum.dlang.org/thread/m81k2p$k47$1 digitalmars.com
My summary of that discussion follows. There were quite a few radical suggestions, some of which were interesting but that seemed to entail a lot of work compared to the reaped benefits. (I have to say it was quite fun to re-read the whole thread and see Walter calmly dismantling some of the less valid arguments.) The suggestions I think are actionable: * Detect `xyz` and replace it with $(BACKQUOTED xyz), pull request in progress at https://github.com/D-Programming-Language/dmd/pull/4228. Maybe detect some __underscored__ or **bolded** words similarly. * Better whitespace control * Macros that expand without $() - possibly an extension of ESCAPES. * Add a subset of markdown on top of ddoc (details unclear). * Make [text](url) denote a link. * Hashtags for headings * Generate cross-references automatically. * Clever automatic linking or embedding of overridden functions docs. * Automatic links to source code. * Simplified signatures (__FILE__ etc, template constraints) * Replace some of the parens with indent nesting. * Not in that thread, but it was somewhere proposed that we use recursive macros for nice $(LIST item one, two, three). What did I miss? Among the more radical proposals: * Use markdown * Use doxygen Again, it seems to me these would yield little benefit for the effort even assuming perfect execution. Andrei
Jan 07 2015
parent reply Jacob Carlborg <doob me.com> writes:
On 2015-01-07 17:22, Andrei Alexandrescu wrote:

 My summary of that discussion follows. There were quite a few radical
 suggestions, some of which were interesting but that seemed to entail a
 lot of work compared to the reaped benefits. (I have to say it was quite
 fun to re-read the whole thread and see Walter calmly dismantling some
 of the less valid arguments.)

 The suggestions I think are actionable:

 * Detect `xyz` and replace it with $(BACKQUOTED xyz), pull request in
 progress at https://github.com/D-Programming-Language/dmd/pull/4228.
 Maybe detect some __underscored__ or **bolded** words similarly.

 * Better whitespace control

 * Macros that expand without $() - possibly an extension of ESCAPES.

 * Add a subset of markdown on top of ddoc (details unclear).

 * Make [text](url) denote a link.

 * Hashtags for headings

 * Generate cross-references automatically.

 * Clever automatic linking or embedding of overridden functions docs.

 * Automatic links to source code.

 * Simplified signatures (__FILE__ etc, template constraints)

 * Replace some of the parens with indent nesting.

 * Not in that thread, but it was somewhere proposed that we use
 recursive macros for nice $(LIST item one, two, three).

 What did I miss? Among the more radical proposals:

 * Use markdown

 * Use doxygen

 Again, it seems to me these would yield little benefit for the effort
 even assuming perfect execution.
Most of the ideas I had might require some redesign of the documentation layout, these are: * Summary of symbols * Documentation for private symbols * Simplified signatures * Links to all base classes and interfaces of a class * Links to all symbols from all base classes and interfaces * Links to all known subclasses BTW the thing that have bothered me the most when writing documentation is there's no good way to even manually cross-reference symbols. We really should have a special syntax for that as well. -- /Jacob Carlborg
Jan 07 2015
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/7/15 11:12 AM, Jacob Carlborg wrote:
 Most of the ideas I had might require some redesign of the documentation
 layout, these are:

 * Summary of symbols
 * Documentation for private symbols
 * Simplified signatures
 * Links to all base classes and interfaces of a class
 * Links to all symbols from all base classes and interfaces
 * Links to all known subclasses

 BTW the thing that have bothered me the most when writing documentation
 is there's no good way to even manually cross-reference symbols. We
 really should have a special syntax for that as well.
The way I see this, these items are good to have and by nature of our process will be deployed (if at all) incrementally by whomever is interested in implementing them. We can't afford to block progress of docs layout on this possibility. -- Andrei
Jan 07 2015
parent Jacob Carlborg <doob me.com> writes:
On 2015-01-07 23:35, Andrei Alexandrescu wrote:

 The way I see this, these items are good to have and by nature of our
 process will be deployed (if at all) incrementally by whomever is
 interested in implementing them. We can't afford to block progress of
 docs layout on this possibility. -- Andrei
I guess that's a fair point. -- /Jacob Carlborg
Jan 07 2015
prev sibling next sibling parent "John Colvin" <john.loughran.colvin gmail.com> writes:
On Tuesday, 6 January 2015 at 22:43:45 UTC, Andrei Alexandrescu 
wrote:
 Let's crowdsource the review. Please check the entries linked 
 from here: http://dlang.org/library/index.html.

 Andrei
I think there needs to a clear separation between the end of the overview (e.g. the cheat sheet in std.algorithm) and the rather arbitrarily organised content beneath. A big header saying "API Reference" or similar would do the trick. I guess it makes sense in a way, but should an end user care that std.algorithm.map happens to be written as a function nested in a template and std.algorithm.find is a function template? I'm not sure. The "name" column in the variable reference tables is often far too narrow. It is *much* harder to get the general feel of a module in the new format, unless it has a comprehensive overview. Previously I would just scan down the page, seeing which symbols had more documentation and examples (probably major entry points to the API), quickly gaining context by having glanced at things on the way through. Now I'd have to go through symbols individually, without context, by laboriously clicking on links. Awful. Overall it's a good idea, but while it will make std.algorithm, std.range and some other well-documented modules with extensive summaries and tables easier to use, it makes less well documented modules even worse than they were before.
Jan 07 2015
prev sibling parent reply "John Colvin" <john.loughran.colvin gmail.com> writes:
On Tuesday, 6 January 2015 at 22:43:45 UTC, Andrei Alexandrescu 
wrote:
 Let's crowdsource the review. Please check the entries linked 
 from here: http://dlang.org/library/index.html.

 Andrei
I don't think I have to point out the problems with http://dlang.org/library/std/algorithm/find.html
Jan 07 2015
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/7/15 8:20 AM, John Colvin wrote:
 On Tuesday, 6 January 2015 at 22:43:45 UTC, Andrei Alexandrescu wrote:
 Let's crowdsource the review. Please check the entries linked from
 here: http://dlang.org/library/index.html.

 Andrei
I don't think I have to point out the problems with http://dlang.org/library/std/algorithm/find.html
Bummer. It doesn't seem ddox is ready for prime time. -- Andrei
Jan 07 2015