YouTube link: https://www.youtube.com/watch?v=cY3wGduNukI
Your hosts: Josh Suereth, Dick Wall, Heather Miller, Daniel Spiewak
As usual, we took live audience questions and comments during broadcast through Google Hangouts Q&A. Also join us during and between episodes for web-based Scalawags chat on Gitter.
- Heather dons her pulsating pirate hat
- Dick: Scaladoc in package objects is sadly underused
- Josh: but you should put overall doc in a user guide instead?
- evil Heather: or maybe scatter the doc across 10,000 blog posts, like everybody else
- evil Daniel: let's not have any documentation at all
- the perpetual problem: documentation falling out of synch with the code
- Dick: use triple curly braces to drop into Scala code
- should Scaladoc support Markdown directly?
- Daniel's brain can't hold any more markup syntaxes. even if Scaladoc is actually older than Markdown
- could Scaladoc be better at alerting you to relevant implicits?
it's already good, but only within the same project
- Daniel shows where it breaks down in Scalaz
- Scaladoc's all-tokens view is great, you should know about it
- history lesson from Heather on some design and technical considerations behind Scaladoc back in the day (~2006)
- Dick recommends Zeal and Dash, offline documentation browsers
- http://zealdocs.org for Linux and Windows
- https://kapeli.com/dash for Mac OS X and iOS
- Dick plugs ENSIME, which adds IDE-like features for Scala to Emacs and other editors
- it's under very active development these days, thx Sam, Rory & co.
- it even supports Sublime and vi these days, sort of, anyway
- Josh still can't decide about API doc vs. user's-guide type doc
- evil Josh: I kinda just want people to read the code
- you can read the Scaladoc in the code, after all
- Heather has a sneaking suspicion that explaining methods one at a time is not the end-all and be-all of documentation
- oh hey, people are asking questions and stuff we should pay attention to
- Heather said "pedagogy"
- it's Jon Pretty's new list of Scala user groups. replaces
the old unmaintained Scala Tribes site
- http://scala.space
- but we Scalawags-dotted it?
- not to be confused with Jon's similarly named conference, Scala World
- wtf Antarctica, get it together down there, show us the love
- is there an intermediate format for Scaladoc? some trees?
- sort of, internally, but there are no hooks
- but the DOM is pretty structured
- bad old days of earlier Scaladoc versions are recalled
- poll, who's actually using ENSIME? a lot of semi-yeses, a lot of yearnings, but, 0 of 4. no actually 1 of 5, Seth uses it
- wasn't there some wiki-style collaborative Scaladoc editing system? there kind of was
- bundling and releasing of code and doc together -- it's good for accuracy, bad for constantly improving doc
- Tut is a library by @tpolecat aka Rob Norris. it makes sure the code in your Markdown doc actually works
- discussion on where it fits in your build
- @milessabin: Scaladoc should have search by type?
- but how to represent complex types, like a function that has such-and-such type constraint?
- Dick: call it Data Access Layer for ENSIME Koding
- @viktorklang: call it Duck Duck Type
- @fommil: the protocols are now Jerky and Swanky
- everybody watch Dick's "Effective Scaladoc" screencast:
- https://www.youtube.com/watch?v=GQxUEAXX_fE
- "some features of Scaladoc you may not know about"
- Scalawags, the podcast of influence
- Dick's desperate cry for SIP and SLIP help
- do it for the stickers (that don't exist)
- democracy, do we believe in it? we don't
- see y'all next time
