How to determine required parameters from Scala API documentation?

Question

I'm having a hard time deciphering Scala API documentation.

For example, I've defined a timestamp for use in a database.

def postedDate = column[Timestamp]("posted_date", O NotNull, O Default new Timestamp(Calendar.getInstance.getTimeInMillis), O DBType("timestamp"))

If I hadn't read several examples, of which none were in the API doc, how could I construct this statement?
From the Column documentation how could I know the parameters?
I guessed it had something to do with TimestampTypeMapperDelegate but it is still not crystal clear how to use it.

score 6 · Accepted Answer · answered Apr 29 '12 at 00:59

The first thing to note from the scaladoc for Column is that it is abstract, so you probably want to deal directly with one if its subclasses. For example, NamedColumn.

Other things to note are that it has a type parameter and the constructor takes an implicit argument of a TypeMapper of the same parameter type. The docs for TypeMapper provide an example of how to create a custom one, but if you look at the subclasses, there are plenty of provided ones (such as timestamp). The fact that the argument is declared as implicit suggests that there could be one in scope, and if so, it will automatically be used as the parameter without explicitly stating that. If there isn't an implicit in scope that satisfies the requirement, you'll have to provide it.

The next think to note is that a TypeMapper is a trait that extends a function with an argument of a BasicProfile and a TypeMapperDelegate result. Basically what's going on here is the definition of a type mapper is separated from the implementation. This is done to support multiple flavors of database. If look at the subclasses of BasicProfile, it will become apparent that ScalaQuery supports quite a few, and as we know, their implementations are sometimes quite different.

If you chase the docs for a while, you end up at the BasicTypeMapperDelegates trait that has a bunch of vals in it with delegates for each of the basic types (including timestamps).

BasicTable defines a method called column (which you've found), and the intent of the column method is to shield you from having to know anything about TypeMappers and Delegates as long as you are using standard types.

So, I guess to answer your question about whether there is enough information in the API docs, I'd personally say yes, but the docs could be enhanced with better descriptions of classes, objects, traits and methods.

All that said, I've always found that leveraging examples, API docs, and even the source code of the project provides a robust way of getting up to speed on most open source projects. To be quite blunt, many of these projects (including ScalaQuery) have saved me countless hours of work, but probably cost the author(s) countless hours of personal time to create and make available. These are not necessarily commercial products, and we as consumers shouldn't hold them to the same standards that we hold for-fee products. If you find docs inadequate, contribute!

Thanks for a really good answer, a lot of good tips on the dechifering front, really appropriate it. If I understand you correctly you describe how the "internal structure although Public API" works. The thing I disagree with you on is that the documentation have enough information. For example if you look at my Default parameter timestamp where in the documentation can I find what it does? I thought at first it inserted a timestamp in the date_posted column automatically, but now I think it's used for creating tables and if I use evolutions it's useless and I it won't use the Default value? — , Apr 29 '12 at 13:54
Another thing I don't agree with you is that we shouldn't hold them to a "commercial" standard. According to http://stackoverflow.com/questions/1362748/wanted-good-examples-of-scala-database-persistence Scala Query is the most mature db framework for Scala. So a better comparison should be against JAVAs Hibernate than some obscure open source hobby project. — , Apr 29 '12 at 14:03
Scala will ship with an integrated query abstraction based on ScalaQuery approximately at the end of this year. From what it looks like, it will be a lot nicer then Java's state of the art. — soc, Apr 29 '12 at 14:45
I'm glad you found the answer useful, and I do understand your pain. From the API guide, Default is a subclass of ColumnOptions. If you consider the other things that are a subclass of ColumnOptions (AutoInc, DBType, NotNull, Nullable, PrimaryKey), you will hopefully arrive at the conclusion that Default allows you to define a default value for the column. The documentation is here: http://scalaquery.org/doc/api/scalaquery-0.9.4/#org.scalaquery.ql.basic.BasicColumnOption$$Default. Unfortunately, Default is a member of an Object, and isn't searchable in the ScalaDoc interface. — jxstanford, Apr 30 '12 at 05:03

How to determine required parameters from Scala API documentation?

1 Answers1