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

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

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

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

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

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

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

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

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

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?