Hi - I’m new here, and I am falling in love with Scala quickly… I love the “scala shell” (is that the right term? What you get by invoking ‘scala’ on the command line), where I do a lot of trial-and-error work. However, one thing that I feel is missing is documentation for the various Scala functions, like in ipython where you can ?xyz and you will see the doc, if any is available. Is that something that would be difficult to implement? Or not desirable for some reason?
3 Likes
http://docs.scala-lang.org links to http://docs.scala-lang.org/overviews/index.html which links to http://docs.scala-lang.org/overviews/repl/overview.html
but it’s rather incomplete — pull requests fleshing it out (via https://github.com/scala/docs.scala-lang/pulls) would be exceedingly welcome
ah, but I think I misinterpreted your question. that’s doc on the REPL itself… I think you’re asking about viewing Scaladoc from the REPL? like, tell me what this method on this class does?
that would be an absolutely fantastic contribution, everyone would love to have that. and no, there’s absolutely no reason it doesn’t exist already.
you’d have to decide whether to try to render the doc in ASCII somehow, or whether to bring it up in the browser. I think opening it in the browser would be much easier to implement, and probably more useful as well since once you’re in the browser everything is hyperlinked. so that’s the starting point I would suggest if someone wants to tackle this.
So behaviour is to be like this:
On command line for REPL, user types ‘?xyz’, and scala doc for xyz opens up in a browser.
1 Like
Ammonite allows you to view the source, which will (hopefully) have the documentation (albeit not in pretty html)
It’s all down to the problem of scaladoc being given little love plus not rendering to any useful document format other than cul-de-sac HTML…
It would be great if Scala could change that and provide a doc tool that extracts doc from source, as before, and publishes it as something that can be consumed by tools.
Best, …h.h…
1 Like
This just reminds me of the long time request for Scala support in DevDocs:
This is correct. You can use source builtin to view sources (in less pager with syntax highlighting, so it’s not bad at all):
@ source(Some(1).map(???))
It can be a bit tricky to use, because you need to call method on a value of particular type you’re interested in. Also you can use ??? or sometimes _ for the missing arguments.
@fastier-li I recommend you to try Ammonite REPL.
1 Like
Having the doc in a browser is great, but then, would that be very different from having a browser open next to the Scala shell and looking up functions in the search window of the browser?
What format should ScalaDoc be rendered to?
@curoli - so in my initial post, I mentioned the example of ipython, which just puts the text doc right there in the ipython shell. The advantage is that you don’t have to jump to a browser to see the doc. The disadvantage is that it’s not nearly as nicely rendered as it can be in a browser.
What format should ScalaDoc be rendered to?
Well, obviously we want to be able to retain the markup; unfortunately scaladoc uses some weird hybrid (?) markup - PmWiki, MediaWiki? - and today it’s safe to say that almost certainly you want either markdown or something less ‘human’ and easier to mechanically process, like YAML, where you could capture things like @see, @param and so on in a manner that is easily parsable. The REPL can just strip markup where it’s not available.
BTW, Dottydoc seems to go that way, although I have no idea whether you can actually plug into it, as a tool, instead of rendering again to HTML like Jekyll.
Perhaps it could be integrated with tab completion somehow, and bring up the Scaladoc for the method you are currently actually trying to use.
1 Like