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 ? :)

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.

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.

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.

On Wednesday, 7 January 2015 at 06:48:23 UTC, Andrei Alexandrescu wrote:
> That would be quite an involved project. -- Andrei

http://dpldocs.info/

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

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

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.

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

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