On Wednesday, 30 December 2015 at 00:32:31 UTC, Andrei
Alexandrescu wrote:
Then why document it?
Just on principle, a documentation tool probably shouldn't be
limiting the author's ability to document...
This might just be a bug in dmd btw. Looking at the ddoc spec
page, it says "documentation comments not associated with a
declaration are ignored", but it doesn't say the declaration must
be named.
Perhaps dmd ought to be keeping it but isn't.
If it's for SEO, what SEO scenarios woukd be covered by this
feature that can't be done with simple workarounds? -- Andrei
Putting one item per page is far more important than I even
realized before getting into this. I was talking to a friend on
Sunday night about his early adventures into D. He's managed to
convert one of his work scripts that works with Google Docs to D
and is working on transitioning a little web form program too.
He consistently found the dlang.org documentation to be
undiscoverable and nearly unusable once he did find it. One
example he gave as wondering if D had an Array.join function like
Javascript.
He searched for "dlang array join" and first, of course, got "did
you mean golang?". I like to joke about that being Google's bias,
but I betcha it is actually more to do with our poor SEO than any
nefarious code on their end.
The top two results he got were:
http://dlang.org/spec/arrays.html
which is no help, it talks about arrays but not the join function
and
http://dlang.org/phobos/std_array.html
which he thought was another false positive because it looked
generic again. I told him it *is* the right page... but the wrong
section. To actually get to the join function, you need to find
it again in the table and hit that second link.
He spent more time than he should have and thought D didn't have
an array.join function because the search engine didn't actually
return it. It returned two pages that are vaguely related but not
specifically what he wanted, and being used to more relevant
search requests, wrote off the ddoc as a false positive despite
it being the right page!
I asked people in the #d chatroom to repeat this experiment.
Nobody even got http://dlang.org/phobos/std_array.html as the top
result! Longer time D users did get
http://dlang.org/library/std/array/join.html as a top result -
good - but nobody actually got the official doc and the ddox only
came to those with personalized search that ups the rank score of
D related pages.
Contrast that to even the primitive results from my dpldocs.info
D-specific search. Look for "array join" and get:
http://dpldocs.info/search/search2?searchTerm=array+join
Whoa, std.array.join is right at the top! And if you click it,
you go directly to the relevant function doc.
That's huge.
