Scaladoc is broken

Indeed, the "abstract" is weird. But it is so nice not to have to look
at the CanBuildFrom stuff.

I am looking at
http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/...,
and it's a big improvement.

I wonder whether it would be possible to go a step further.

So much of the inheritance hierarchy in the collections library is
implementation detail. Library consumers have no interest in
GenTraversableOnce vs. TraversableOnce vs. GenIterable or GenSeq vs.
Seq.

It would be nice if there was a view of the API that used a handful of
types that an end-user can easily comprehend, with the possibility of
revealing the whole truth to the experts.

In the case of ArrayBuffer, one could show Iterable and Seq, and
greatly reduce the apparent complexity of the API.

It's a judgment call what to display, so there should be some
annotation to drive it. Frankly, it really should be a part of
designing a library to think of this aspect of the client view. As we
have learned, clients are not amused when they are presented with a
blizzard of traits.

Cheers,

Cay

On Wed, Dec 7, 2011 at 5:18 AM, Daniel Sobral wrote:
> I understand the idea behind use cases, and I understand the idea
> behind *hiding* the actual methods when a use case is present.
> However, use cases are broken in ways that have nothing to do with
> displaying a false type signature, and the lack of documentation for
> the actual methods makes the issue critical, in my opinion.
>
> Please refer to https://issues.scala-lang.org/browse/SI-5287 for details.
>
> See methods foreach and map on Range for examples of broken documentation.
>
> --
> Daniel C. Sobral
>
> I travel to the future all the time.

On Wed, Dec 7, 2011 at 12:46, Cay Horstmann wrote:
> Indeed, the "abstract" is weird. But it is so nice not to have to look
> at the CanBuildFrom stuff.

It's not simply a question of weirdness. What will happen when
someones decide to implement an Iterator and sees dozens of abstract
methods? What will happen when one figures on extending Range, and
finds out that the method he is overriding is final? Things like
"abstract" and "final" are very important.

And, of course, the present state makes it unusable for anyone who
actually needs correct information, but I'm leaving that unchallenged
for now. I just don't want the docs to be broken for beginners *and*
expert users alike.

On Wed, Dec 7, 2011 at 6:57 AM, Daniel Sobral wrote:
> And, of course, the present state makes it unusable for anyone who
> actually needs correct information, but I'm leaving that unchallenged
> for now. I just don't want the docs to be broken for beginners *and*
> expert users alike.

You're right. There's no way I can jump into fixing scaladoc right
now or anytime in the foreseeable future, so I will have to depend on
the kindness of strangers to do something sensible here. But the tail
is wagging the dog when we are so keen on burying the scary stuff that
people can't even dig it back up when they need it and the less scary
stuff we left in its place is leaking radiator fluid.

Hi,
There are two problems that got merged into one:
1 - the annotations for use cases are wrong -- they have been like this forever, just that they were not visible (see the discussion on SI-5054) -- I'm currently looking at the problem 
2 - the full signatures are not displayed under the use case -- the use case contains the full signature in the model, it's just not displayed in the scaladoc page. I made an attempt to enable it here, but didn't merge it into trunk as Heather will do it the right way.
Speaking of which, can we consider bug SI-5287 a duplicate of SI-5054? If not, what are the new problems compared to SI-5054?

Vlad

On Wed, Dec 7, 2011 at 11:27 AM, Vlad Ureche wrote:
> 2 - the full signatures are not displayed under the use case -- the use case
> contains the full signature in the model, it's just not displayed in the
> scaladoc page. I made an attempt to enable it here, but didn't merge it into
> trunk as Heather will do it the right way.

However that is not enough. If these "simplified" signatures are
really going to be front and center, then it seems kind of important
that they not be completely wrong.

Mother... I can't @#$%! cut and paste from the scaladoc, all I get is
"()". OH MY GOD IT IS MADDENING ALWAYS WITH PROGRESS MAKING THE
SIMPLE THINGS IMPOSSIBLE WHY WHY

So if I could cut and paste the signature of map from MapLike, rather
than just describing it as I am presently doing, you would see that
"B" is used to mean two different Bs. It's completely wrong. Anyone
trying to make sense of it would lose their mind.

https://issues.scala-lang.org/browse/SI-3834

That's created in September of 2010. I don't know what to say about
except that maybe people should thank me for writing so little
documentation because at least the documentation I don't write
corresponds to reality.

On Wed, Dec 7, 2011 at 18:16, Paul Phillips wrote:
> On Wed, Dec 7, 2011 at 11:27 AM, Vlad Ureche wrote:
>> 2 - the full signatures are not displayed under the use case -- the use case
>> contains the full signature in the model, it's just not displayed in the
>> scaladoc page. I made an attempt to enable it here, but didn't merge it into
>> trunk as Heather will do it the right way.
>
> However that is not enough. If these "simplified" signatures are
> really going to be front and center, then it seems kind of important
> that they not be completely wrong.
>
> Mother... I can't @#$%! cut and paste from the scaladoc, all I get is
> "()". OH MY GOD IT IS MADDENING ALWAYS WITH PROGRESS MAKING THE
> SIMPLE THINGS IMPOSSIBLE WHY WHY
>
> So if I could cut and paste the signature of map from MapLike, rather
> than just describing it as I am presently doing, you would see that
> "B" is used to mean two different Bs. It's completely wrong. Anyone
> trying to make sense of it would lose their mind.

It just pasts a new-line between the def and the rest:

def
map[B](f: ((A, B)) => B): immutable.Map[B]

Still, I can copy&paste it with no problem.

>
> https://issues.scala-lang.org/browse/SI-3834
>
> That's created in September of 2010. I don't know what to say about
> except that maybe people should thank me for writing so little
> documentation because at least the documentation I don't write
> corresponds to reality.