Ceylon Vert.x docs contain errors

[lukehutch]

The docs for using Vert.x in Ceylon docs have numerous omissions and errors.

1. The required imports are not listed (and the Ceylon Vert.x class names are often the same as the ceylon.http class names)
2. Imports need to be renamed currently (I'm not sure of the reason why) -- i.e. you can't use value vertx = vertx.vertx(); as suggested in the vertex.core docs, you need import io.vertx.ceylon.core { vertx_=vertx } then value vertx = vertx_.vertx();.
3. You can't use => and {} together in lambda expressions, e.g. (RoutingContext routingContext) => { } should actually be (RoutingContext routingContext) { }.
4. The code in the section "Handling requests and calling the next handler" is wrong -- only the handler defined for route1 is ever called, the timer that calls .next() never ends up calling the code for route2. I haven't figured out why yet.

Has anybody actually tried to work through these examples from beginning to end? It seems like there's something wrong with every example I have tried so far.

[vietj]

hi, the examples are generated by a generator from java examples. The other generators (for JavaScript, Groovy and Ruby) are better than the Ceylon one as of today and the Ceylon generator should be improved to fix the problem you are listing.

1. yes this could be done I think.
2. probably that the imported objects should be suffixed with _ for example as you are saying
3. good catch
4. the example is probably wrong indeed

[vietj]

btw the code translator can be found here if you are curious https://github.com/vert-x3/vertx-lang-ceylon/tree/master/vertx-lang-ceylon-doc/src/main/java/io/vertx/codetrans/lang/ceylon

[lukehutch]

Interesting approach to doc creation! Makes sense that these should be generated automatically from a set of canonical examples in Java.

I suggest working through the examples from top to bottom at some point... there are lots of gotchas!

[vietj]

I pushed improvements for the addressable points:

• => is now gone
• type containing functions (like buffer or vertx) are now imported, when such import collides with a local declaration of the same name, the import is aliased with a trailing _ as you suggested.

[lukehutch]

Thanks for fixing these issues.

(I saw the trailing '_' notation in some Ceylon example code, so I assume it's idiomatic, but I'm new to Ceylon...)

Did try to reproduce the problem in my 4th point? I don't think it's a problem with the example code, I think it's a problem with the bindings themselves. (Sorry to list multiple bugs in one problem report...)

[vietj]

I haven't yet looked at it, as I focused on the cosmetic doc points. I will have a look now. I'll open an issue if needed.

[vietj]

and will ref it from this issue

[vietj]

I just tried the example and indeed I only see "timer1" (when corrected).

But if I add print() statements, then it works fine, see:

  shared actual void start() {    

    value router_ = router.router(vertx);

    router_.route("/some/path/").handler((RoutingContext routingContext) {

      value response = routingContext.response();
      // enable chunked responses because we will be adding data as
      // we execute over other handlers. This is only required once and
      // only if several handlers do output.
      response.setChunked(true);

      print("route1");
      response.write("route1\n");

      // Call the next matching route after a 5 second delay
      routingContext.vertx().setTimer(500, (tid) {
        // response.write("timer1\n");
        print("timer1");
        routingContext.next();
      });
    });

    router_.route("/some/path/").handler((RoutingContext routingContext) {

      print("route2");
      value response = routingContext.response();
      response.write("route2\n");

      // Call the next matching route after a 5 second delay
      routingContext.vertx().setTimer(500, (tid) {
        // response.write("timer2\n");
        print("timer2");
        routingContext.next();
      });
    });   

    router_.route("/some/path/").handler((RoutingContext routingContext) {

      print("route3");
      value response = routingContext.response();
      response.write("route3");

      // Now end the response
      routingContext.response().end();
    });     

    vertx.createHttpServer().requestHandler(router_.accept).listen(8080);
  }

[vietj]

ok so the reason is that it does not work is that the generated code is wrong:

(tid) => {
  routingContext.next();
}

means actually : returns (=>) an Iterable ({ ... }) that is lazy evaluated.

so the correct code is to use:

(tid) => routingContext.next()

or

(tid) { routingContext.next(); }

so this is an issue related to the doc generator.

[lukehutch]

Makes sense. BTW I suggest renaming the imports with underscore, not the local variables -- this will make for cleaner code.

[vietj]

that's what I did

[lukehutch]

? The example you pasted above has

value router_ = router.router(vertx);

instead of

value router = router_.router(vertx);

but maybe the code above does things differently than the code generator.

[vietj]

ah, this is real code I wrote in Ceylon IDE, that's why it's not aliased like in the doc. When I'm done with improvements I'll repost here the result :-)

[vietj]

now the generated code is:

value route1 = router.route("/some/path/").handler((RoutingContext routingContext) {

  value response = routingContext.response();
  // enable chunked responses because we will be adding data as
  // we execute over other handlers. This is only required once and
  // only if several handlers do output.
  response.setChunked(true);

  response.write("route1\n");

  // Call the next matching route after a 5 second delay
  routingContext.vertx().setTimer(5000, (Integer tid) => routingContext.next());
});

value route2 = router.route("/some/path/").handler((RoutingContext routingContext) {

  value response = routingContext.response();
  response.write("route2\n");

  // Call the next matching route after a 5 second delay
  routingContext.vertx().setTimer(5000, (Integer tid) => routingContext.next());
});

value route3 = router.route("/some/path/").handler((RoutingContext routingContext) {

  value response = routingContext.response();
  response.write("route3");

  // Now end the response
  routingContext.response().end();
});

[vietj]

the website online doc has been updated with the refreshed docs : http://vertx.io/docs/vertx-web/ceylon/

[lukehutch]

Great, thanks for your work on this.
On Jan 4, 2016 7:13 AM, "Julien Viet" notifications@github.com wrote:

the website online doc has been updated with the refreshed docs :
http://vertx.io/docs/vertx-web/ceylon/

—
Reply to this email directly or view it on GitHub
#2 (comment)
.