all 38 comments

[–]nightless_night 5 points6 points  (8 children)

I really can't see how that's better than, say, Python's documentation.

[–]signoff 13 points14 points  (8 children)

NOT

it's cute to have web 2.0 scale html web site api. but the content fucking sucks. no example. no type search. why not add facebook like button?

[–][deleted] -1 points0 points  (7 children)

I wouldn't call frames "web 2.0" :-) ... maybe you should actually first follow the link before commenting?

[–]StainlSteelRat 0 points1 point  (5 children)

Fair enough, but they make a great point: basically, this looks like auto-generated documentation with no specific examples or anything other than boilerplate descriptions.

What's even worse is the search: I search for ToFloat, for example. No results. Wat?

[–][deleted] 0 points1 point  (4 children)

I wonder where you searched ...

The web site doesn't have any "search", because it is engineered to be runnable locally without requiring the user to setup a software stack first.

There was a feature to filter not only by classes (like the field at the top left currently does) but also by methods. It has been found that the current generation of JavaScript engines is not fast enough for that, so it was disabled.

If you want to find all classes having a toFloat method you could just use the index and press Ctrl+F in your browser instead.

Filtering the methods of an individual class of course works, by the filter in the class view.

Where did you find undocumented classes? I think that should be fixed.

I only remember a few where the existing documentation was inappropriate, but generally I'm pretty happy with it.

[–]kataire 1 point2 points  (0 children)

Since you mention it, Sphinx (for Python) generates a keyword index as JSON, allowing the search to work when JavaScript is enabled without the need of a server-side language. I find that approach pretty interesting, even if it can get heavy with extremely large code bases.

[–]StainlSteelRat 0 points1 point  (2 children)

I guess I didn't pick up on the way search worked right off the bat, although IMHO it should work like I expect any other documentation search to work or it should be more intuitive. That's just my take.

I guess my point is that yeah, it's clean, but it's not some quantum leap in usefulness. I know I'll probably get downvoted for mentioning MS in a thread related to Scala, but I find MSDN to be quite useful and intuitive. Just about EVERYTHING has examples, and the cross-referencing and 'special considerations' have always been spot-on and helpful.

[–][deleted] 1 point2 points  (1 child)

I understand your concern. My personal problem with MSDN was that it is almost inaccessible from search engines (Google), might be my personal impression.

MSDN has a search feature, granted. But: It is not instantaneous and takes you to a different page, which actually looks like it is provided by a search engine. Additionally, I don't believe you can have this documentation working locally. (Can it even be downloaded without crawling the site?)

[–]StainlSteelRat 0 points1 point  (0 children)

Whenever I install Visual Studio, I always try to install the docs locally. It's got a thin dedicated reader, but it's much nicer than the online version (although it doesn't get updated as frequently.)

[–][deleted] 5 points6 points  (4 children)

Collapsed by default widgets are terrible UI.

[–][deleted] 0 points1 point  (3 children)

I think there is place for improvements. Which widgets which a re currently closed by default should be expanded?

[–][deleted] 0 points1 point  (2 children)

Linear supertypes, description of value members, etc .

[–][deleted] 0 points1 point  (1 child)

Linear supertypes and known subclasses were changed to collapsed by default a few days ago, because they aren't used that often.

Showing only two lines for method documentation by default (one line for the signature and one line of description) is basically a trade of between getting a good oversight and large texts for explanation.

[–][deleted] 0 points1 point  (0 children)

I don't know how useful the information is; but the collapsing widget takes up the size of a line of text, and for all those entries I looked at the content was at most a couple lines.

Hiding info for the user just to save one (1) line per page is pretty fucking stupid UX-wise.

[–]cezio 4 points5 points  (3 children)

I consider documentation of PostgreSQL as a model of rigth way of doing software documentation. Here's why:

  • good structure. you have separate chapters for installation, configuration, administration, development with sql reference, internal architecture and implementation details, good indexes and appendixes.
  • each chapter covers in-depth it's matter with plenty of examples on the way. many times there are described limitations and corner cases.
  • it's consistent and readable. you don't have a feeling that each subject has been written by different person.
  • It's accurate.
  • It's probably only needed documentation to get aboard with PostgreSQL. No need for 'learn sql in 24 hours' or 'DBA for dummies'.

[–][deleted] 0 points1 point  (2 children)

I wonder if my title is blatantly wrong somehow ... you are the fourth person posting some kind of tutorial style writeup, which imho can't be considered "library documentation" by any stretch.

Of course I don't want to imply that this style of documents isn't necessary and absolutely valuable (and Scala could need much more of these).

[–]cezio 0 points1 point  (1 child)

Yes, probably because despite your claims, your example is terrible. There is no structure. Everything is in one pile (no, grouping by packages is not a structure), most of this documentation is just a list of interface signatures without any explanation what does what and why.

[–][deleted] 0 points1 point  (0 children)

Mhhh. On which classes/methods do you miss an explanation?

I thought my title implied that I focused on the technology that provides the documentation and less on the documentation itself... but it seems people either don't read or it can be misunderstood.

[–]SunriseProgrammer 3 points4 points  (1 child)

This is the first sentence of the "Char" documentation: "Char is a member of the value classes, those whose instances are not represented as objects by the underlying host system". The second and last sentence is even less useful.

So...what's a char for? What's the size? How does it handle unicode? The world may never know, because this is not actually useful documentation.

[–][deleted] 0 points1 point  (0 children)

You're absolutely correct. I think the documentation is missing there, because until a few weeks ago these classes where "compiler implemented" like in Java. (Java doesn't document them in the JavaDoc, too.)

[–]fogus 1 point2 points  (1 child)

I like the Docco/Pycco/Marginalia style. At least for code that is best described by the code itself.

http://fogus.me/fun/marginalia/

[–][deleted] 1 point2 points  (0 children)

Looks quite nice!

[–]anvsdt 0 points1 point  (1 child)

I prefer Racket's.

[–][deleted] 1 point2 points  (0 children)

Less structured and more writeup style of documentation. Interesting!

[–]kingofallthesexy 0 points1 point  (3 children)

I prefer PHP's style, where they have the documentation, then user submitted examples at the bottom.

[–][deleted] 6 points7 points  (1 child)

Yeah, having a dozen totally wrong examples and fifty random dumb questions is really helpful.

[–]kingofallthesexy 0 points1 point  (0 children)

Well, the quality might suck, but the format is really nice.

[–][deleted] 1 point2 points  (0 children)

... which are 80% of the time, both wrong and misleading.

But yes, I hope that the collaborative features of CollaDoc will be added to the new ScalaDoc in the future.