Doc fixes

[adamw]

This contains the same change as #96, plus a code change to the protocol definition so that it compiles, and an explanation on what the macro generates (it wasn't obvious to me at first)

[ahjohannessen]

FYI, if you wish to get the old behavior you can use this:

import remotely._
import Field._
import shapeless.HList
import shapeless.ops.hlist.{Selector, Prepend}
import scala.reflect.runtime.universe.TypeTag
import scalaz.\/
import scalaz.syntax.either._

object protocol {

  /// Convenience Syntax

  implicit class ProtocolOps[I <: HList](inner: Protocol[I]) {

    def ++[O <: HList](other: Protocol[O])(implicit p : Prepend[I, O]): Protocol[p.Out] = {
      val c: Codecs[p.Out] = inner.codecs ++ other.codecs
      val s = Signatures(inner.signatures.signatures ++ other.signatures.signatures)
      Protocol(c, s)
    }

    def define0[O:TypeTag](name: String)
      (implicit SO : Selector[I, O]): Protocol[I] = inner.specify0(name, Type[O])

    def define1[A:TypeTag,O:TypeTag](name: String)
      (implicit SA : Selector[I, A], SO : Selector[I, O]): Protocol[I] = {

      val f1 = strict[A]("in1")

      inner.specify1(name, f1, Type[O])
    }

    def define2[A:TypeTag,B:TypeTag,O:TypeTag](name: String)
      (implicit SA : Selector[I, A], SB : Selector[I, B],
                SO : Selector[I, O]): Protocol[I] = {

      val f1 = strict[A]("in1")
      val f2 = strict[B]("in2")

      inner.specify2(name, f1, f2, Type[O])
    }

    def define3[A:TypeTag,B:TypeTag,C:TypeTag,O:TypeTag](name: String)
      (implicit SA : Selector[I, A], SB : Selector[I, B],
                SC : Selector[I, C], SO : Selector[I, O]): Protocol[I] = {

      val f1 = strict[A]("in1")
      val f2 = strict[B]("in2")
      val f3 = strict[C]("in3")

      inner.specify3(name, f1, f2, f3, Type[O])
    }

    def define4[A:TypeTag,B:TypeTag,C:TypeTag,D:TypeTag,O:TypeTag](name: String)
      (implicit SA : Selector[I, A], SB : Selector[I, B],
                SC : Selector[I, C], SD : Selector[I, D],
                SO : Selector[I, O]): Protocol[I] = {

      val f1 = strict[A]("in1")
      val f2 = strict[B]("in2")
      val f3 = strict[C]("in3")
      val f4 = strict[D]("in4")

      inner.specify4(name, f1, f2, f3, f4, Type[O])
    }

  }
}

[adamw]

Ah, didn't notice that, thanks :)
Which form would you encourage for new users? That's what should go into the docs, I suppose :)

[ahjohannessen]

@timperrett I think the new DSL is a bit unfriendly compared to what we had. Perhaps we should add the convenience syntax above to the core library and document differences. However, this makes little sense if the plan is to introduce some higher level DSL that is even more friendly to use.

[ahjohannessen]

Which form would you encourage for new users? That's what should go into the docs, I suppose :)

I did that ProtocolOps because I dislike the boilerplate introduced by Field and Type. I understand the rationale behind the types, but not so much in a DSL.

[adamw]

Ah I see :) specify1 stays there for now then

[timperrett]

@ahjohannessen what's your take on this? Think we should add that convenience object you pasted in your comment to the actual code base - I agree the current setup is quite verbose and not that great for a DSL.

@runarorama @stew what do you guys think?

[ahjohannessen]

@timperrett My take on using hlist on Codecs, after using it in anger for a while, is that I do not really see the point of it and compile times are not great. I have a related issue - #110 - around that. However, if hlists are not being removed, then I think it makes sense to provide that convenience object as the current setup is bad wrt. DSL.