Document Database Config somewhere that isn't in the scaladoc

[joearasin]

The usability of burying the database config documentation in a collapsed field of Scaladoc is not good. "How do I configure this thing?" is one of the first questions users will have re: slick, and it's not particularly discoverable that what is effectively the manual is buried in a collapsed Scaladoc entry (which typically tends more towards discussion of implementation details than vital information).

[cvogt]

@joearasin do you have a suggestion where to best mention it in the docs. A PR would be ideal, Slick is free software and relies on all of our contributions to be better :).

[joearasin]

Here, perhaps: http://slick.lightbend.com/doc/3.1.1/gettingstarted.html#database-configuration

[joearasin]

or, rather, here: http://slick.lightbend.com/doc/3.1.1/database.html -- There's the parenthetical "(see the API documentation of this method for details on the configuration parameters)", but clicking on it doesn't bring you to something that is obviously useful.

[cvogt]

so there is this section: http://slick.lightbend.com/doc/3.1.1/gettingstarted.html#database-configuration What are you missing?

[cvogt]

And what part of the scaladoc are you referring to?

[joearasin]

Now that I think about it, the potentially trivial-to-implement thing that would be useful (and I don't know if it's possible) is having the link to the scaladoc automatically open the collapsed "forConfig"

[cvogt]

we can link to it like this

http://slick.lightbend.com/doc/3.1.1/api/index.html#slick.backend.DatabaseConfig$@forConfig[P<:slick.profile.BasicProfile](path:String,config:com.typesafe.config.Config,classLoader:ClassLoader)(implicitevidence$1:scala.reflect.ClassTag[P]):slick.backend.DatabaseConfig[P]

won't open but highlight

[joearasin]

I think the issue I really want to file is on Scaladoc itself, allowing permalinks to open entries.

[cvogt]

cc @felixmulder

[felixmulder]

Hmm, should probably open - but not sure on the current URL scheme. As long as it is a field or method it should expand. Look at something like the stdlib and the linking done between methods or top-level packages?

[felixmulder]

Also, chrome is the most tested browser afaicr

[felixmulder]

The link posted by @cvogt is the old scheme - will have a look when I'm not on mobile

[felixmulder]

Sorry for the late response (my mac has risen from the dead, huzzah! 🎉), the new scheme looks like this:

http://www.scala-lang.org/api/current/scala/collection/immutable/List.html#+:(elem:A):List[A]

This will open scala.collection.immutable.List#+: (unfolded and scroll to), so the url you're looking for is something like:

http://slick.lightbend.com/doc/3.1.1/api/slick/backend/DatabaseConfig$.html#forConfig[P<:slick.profile.BasicProfile](path:String,config:com.typesafe.config.Config,classLoader:ClassLoader)(implicitevidence$1:scala.reflect.ClassTag[P]):slick.backend.DatabaseConfig[P]

Beware that since the scheme has changed from 2.11, there we're sort of in a bind when it comes to cross-published libraries. If you feel that this is an annoyance - please make a PR to scala/scala fixing this, and everyone will 👍 ❤️

[cvogt]

@felixmulder are old links no longer working with the new scaladoc?

[felixmulder]

The new scaladoc has a different layout for the static site. The old one had a single index file and used iframes to load all content.

This destroys the browser's caching and worked poorly on mobile devices. So, we decided to use a different layout. IIRC, new links work with the old layout but not vv. This is due to the old one redirecting to the root index and applying the path given.

There's a caveat with this where package objects don't accept these links. I think there's an issue open for it.

[cvogt]

I see. All in agreement with your changes providing a better user experience for Scaladoc. I am worried about old links no longer working as it will break documentation sites and is quite hard to identify until somebody tries the link. I know Slick's documentation makes heavy use of the old links. Not sure what other libs do, too.

Doing an automatic translation for the old links shouldn't be too hard.

index.html#slick.backend.DatabaseConfig$@...
needs to be detected by javascript and lead to a redirect to
slick/backend/DatabaseConfig$.html#...