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