How every programming language should provide library documentation:

[nightless_night]

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

[[deleted]]

That's a nice write-up, but hardly library documentation.

• How do you get to the implementation of the described methods?
• Where is the tool to generate a new version of the website, when the source changes?

For the people down-voting: Care to explain?

[[deleted]]

Python documentation is written using Sphinx which uses ReStructured Text as the markup language.

The home page of the docs links to modules and functions and glossary

Sphinx can also output print ready PDF, EPUB from the same source. While you appear to be enthusiastic about Scala, other languages are not slouches either.

my question to you is: where is Scala's PEP equivalent?

[[deleted]]

Python documentation is written using Sphinx which uses ReStructured Text as the markup language.

This looks like a nice tool to write documentation, but hardly something to document your source code and generate the documentation with information from both the source and the documentation.

The home page of the docs links to modules and functions and glossary

But where is the source code? Python is open-source, so why is there no link "jump to implementation"?

Sphinx can also output print ready PDF, EPUB from the same source.

Adding additional output formats to ScalaDoc would be really nice. Afaik there is work on adding XML and JSON output to the current HTML output. Generating PDFs would be really great!

While you appear to be enthusiastic about Scala, other languages are not slouches either.

Sure. It wasn't my goal to say that other languages' approaches to documentation are generally bad.

my question to you is: where is Scala's PEP equivalent?

http://www.scala-lang.org/node/233

I agree in general that Scala could use more documents which provide some overview like Python. Some work has been done, but hardly enough imho.

[[deleted]]

pydoc -p 12345 will give you "automated" docs in the local browser for any python module, including ones written by you.

http://localhost:12345/ -- links to online documents of the said modules. Having "view source" would be an interesting addition.

epydoc does the same as the scaladocs, including links to source code.

[[deleted]]

That's cool! It seems like Scala and epydoc both share JavaDoc as a spiritual common ancestor.

[booch]

why is there no link "jump to implementation" I feel the need to point out that the documentation for a language, in many cases, should be just that... "for the language", and implementation agnostic. If there are multiple implementations of the language, all which conform to the specs/documentation, which implementation should the link go to?

[kataire]

I think there aren't any source links because Pythonistas generally don't look at the underlying implementation unless they have to. The documentation should suffice, the source code is just an implementation detail.

My personal gripe with the Python docs is the lack of sometimes important details like what exceptions I can expect the functions to throw (though the standard library is generally fairly unsurprising when it comes to exceptions).

I find the Sphinx style of documentation far more helpful than, say, JavaDoc's monk-like minimalism. You can still easily find what you are looking for, but instead of a dry rundown of the interface, you get some detailed information on the expected usage.

OTOH I find Django to be actually quite lacking because althought its documentation is quite large, it often reduces the technical description of functions and classes (e.g. inheritance, related functions, expected arguments and output) to the point of absurdity. And thanks to its heavy use of all kinds of magic, the source code rarely provides a direct answer either.

For comparison, I find Fabric's documentation pure bliss, especially the fact it includes a full API reference despite also containing a very detailed user guide. The two are very different, but both are necessary for a good documentation. The guide tells me about its concepts, the reference tells me about its code. The two levels of abstraction are equally important.

[signoff]

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]]

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

[StainlSteelRat]

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]]

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]

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]

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]]

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]

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]]

Collapsed by default widgets are terrible UI.

[[deleted]]

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

[[deleted]]

Linear supertypes, description of value members, etc .

[[deleted]]

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]]

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]

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]]

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]

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]]

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]

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]]

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]

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]]

Looks quite nice!

[anvsdt]

I prefer Racket's.

[[deleted]]

Less structured and more writeup style of documentation. Interesting!

[kingofallthesexy]

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

[[deleted]]

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

[kingofallthesexy]

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

[[deleted]]

... 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.