Scalawags #31

thescalawags's podcast

Scalawags #31: What we want from Scaladoc

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.

Intro (0:00)

• Heather dons her pulsating pirate hat

All things Scaladoc (2:40)

• 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

ENSIME (25:35)

• Dick plugs ENSIME, which adds IDE-like features for Scala to Emacs and other editors
  • https://github.com/ensime/ensime-server
• it's under very active development these days, thx Sam, Rory & co.
• it even supports Sublime and vi these days, sort of, anyway

More Scaladoc (27:20)

• 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 my god, it's full of audience (33:20)

• oh hey, people are asking questions and stuff we should pay attention to
• Heather said "pedagogy"

Scala Space (35:45)

• 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

Scaladoc Q & A (39:30)

• 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 (53:10)

• Tut is a library by @tpolecat aka Rob Norris. it makes sure the code in your Markdown doc actually works
  • https://github.com/tpolecat/tut
• discussion on where it fits in your build

Scaladoc Q & A (56:40)

• @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

SIPs and SLIPs (1:03:10)

• 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

Conclusion (1:05:30)

• see y'all next time