Is this readable to Rust people? I mean, can you look at this and say, "ah ok, I'm gonna call this and that then I'll have the state" directly?
I'm lost but I have zero Rust knowledge so this is a sincere question, does this mess make sense when you get into it?
I think rustdoc needs quite a lot of work in general. For example it doesn't even give a list of methods at the start of each type's page. Want to know which methods you can call on a `String`? Enjoy scrolling...
It does. Honestly, it's quite hard to contribute to at the moment. This is going to improve in the very near future; there's a PR in the queue that's the start of the ability to start making it easier. I hope to make it vastly so someday in the future. Always so much work to do...
A bit more summary of available methods/trait impls somewhere would be nice.
I'd appreciate a three scrollable pane setup, first pane similar to whats already there on the left, but always visible. Second pane type, usage, examples, methods, impls. Third pane in the middle, widest, actual information in long form. Inline examples of each method are incredibly helpful and the std library docs have quite a few of those but not always. Its sometimes hard to understand how to use a method or type or impl depending on its signature.
Panes should scroll+highlight currently viewed items in the actual doc (third) pane.
With rustdoc you have to click on the [-] in the top right to get an overview of the available methods.
But yes, once I have that overview I can usually pick out the methods I need. The type signatures can be a little complex, but so are C++ templates.
[0] http://download.java.net/java/jdk9/docs/api/java/util/Option...
But a few weeks in, it started to make total sense, and now I see the page you link to and I'm like «That's pretty clear, no problem here». It just takes a little time to get used to the documentation syntax and formatting I guess.
It's often easier to work from examples though, but I do know that you often see interesting ways to do things when you look at API docs.
OT: the framework looks interesting... routing as attributes is pretty cool, would be nice if one of the examples on the main page used a route variable though. I am curious how this compares in terms of requests/second of hello world vs. alternates... I would imagine the memory overhead would be much lower, but curious on throughput for the underlying model.
Unfortunately Rust is not as revolutionary in this regard as in others :/ but other languages/ecosystems/tools are just as bad :(
Specifically, the first thing, inner(), says that you generally don't have to call it because there's a Deref implementation. Deref is a trait that lets you implement things that loosely resemble smart pointers or similar wrapper types: for instance, CString, which tracks a Rust-owned C-compatible string (null-terminated), has a Deref implementation to an array of bytes. So I know that I can usually use a State<T> when a function seems likely to want an &T or Box<T> or similar, and I can carry on and not care very much more until I need to.
The rest are trait implementations of common traits (Debug is like Python's repr, PartialEq and Eq are comparisons, etc.), and the documentation is from the trait. I think this is a rustdoc weakness, but I know about it, so I can ignore reading the docs.
In fact it's a pretty awesome example of Rust's traits in practice since it requires Sync + Send so you know it needs to be thread safe(and the type system will enforce it).
Like any notation, once you understand how to break it apart and you learn what symbols mean, it becomes easier to interpret large fragments like this.
One pretty significant issue for newcomers is that rustdoc emphasises traits, rather than methods. Sometimes there is more indirections. It takes more insider knowledge to know that fmt() is actually called by the println!() macro, so you're unlikely to encounter that method unless you're digging into the internals.
If you know Rust, it's pretty easy to cut through it if you know what you're looking for, and sometimes it's actually useful.
Many libraries are made of boring top-level code and then interesting trait implementations. Structuring the documentation like the code doesn't work out very well in that case.
Paging steveklabnik, what do you think?
I find it readable, it's saying that the "inner" function returns a reference to the value the State object is containing (which must be of a type that implements Send and Sync), and that reference cannot outlive the State object the value was returned from.
But damn, there's a lot of compiler magic in order to simplify the request and response signatures.
It would be great to see more documentation on how to deal with naked Request/Response objects that can be constructed by hand. I'd love to use Rocket to develop some API on top of it, but that means I want more access to the underlying objects below.
Now, when this works on stable, it'll be awesome!
Managed state is a feature specifically designed to help with this kind of thing. That being said, I still think Rocket can do more to abstract away database connections. I'm tracking improvements on this front in GitHub issue #167 [2].
[0]: https://github.com/SergioBenitez/Rocket/tree/master/examples...
[1]: https://github.com/SergioBenitez/Rocket/blob/master/examples...
I've got an API server started in Iron, but I have to say the claims of productivity and less code overhead that Rocket is proclaiming seem pretty nice right about now.
Source; I build secure financial services software day to day.
Personally I think some big gains in documentation clarity could be made by sorting the methods differently, possibly more compactly; I remember when I was first starting with Rust it was easy to overlook trait impls, e.g. a useful `Deref<[T]>` implementation because they tend to show up further down in the docs.
I might also have benefited from a clearer overview of all the core traits in one place, especially the ones having to do with taking references. IIRC `Deref`, `Borrow`, and `AsRef` are all different traits and the differences between them (and how to idiomatically use them in common patterns) are not totally clear. But maybe I just skipped a chapter of "the book" or something.
I expect that the interface works this way in an attempt to avoid parsing format strings at run time ("zero cost abstractions" and all that), and that's great, but the lack of documentation made it pretty miserable to use, and I would classify my Rust skills as "intermediate". I expect a beginner would have just given up (and taken to HN to complain about the learning curve).
DateTime::format seems to do the same thing as strftime, with a format string parsed at run-time.
I definitely think the defaults should have everything except the description at the top collapsed.
Insisting that either your tiny web application that can do next to nothing is the thing that owns 80/tcp (and/or 443/tcp) or runs behind a HTTP proxy is stupid. Proxying HTTP requests properly is harder than it sounds, which is surprising every now and then and thus is easy to screw up (what happens to Host: header? who is the TCP client? is it HTTP or HTTPs?), and your tiny web application, as I've called it, is not the only thing I want to host on the machine.
Edit: You can run multiple apps on separate ports, so that shouldn't be an issue.
Well, there are people who can say the same about Node.js or RoR. Not that it makes a majority.
> When you use something like nginx, it's really not hard at all to get right.
It's not a matter of nginx. It's a matter of what assumptions are hardcoded in the application.
> Edit: You can run multiple apps on separate ports, so that shouldn't be an issue.
Of course it is an issue. Such a deployment looks terrible at best.
I only met FastCGI in PHP. All NodeJS apps I saw used HTTP.
Is there any benefit of doing it that way?
How does it work with WebSockets?
And I met FastCGI in Python, Perl, Ruby, and Erlang (though I haven't used the last one yet). Oh, and uWSGI can expose anything it runs through FastCGI.
My personal opinion is that web crowd (most of JavaScript programmers fall in here) just doesn't want to learn from anybody else.
> Is there any benefit of doing it that way?
Compared to running the tiny web application on 80/tcp? Sure: I can run more than one and I don't need root privileges for the application.
Compared to running the application behind a reverse proxy? Ditto: it's virtually impossible to get the setup wrong, so it's easier in the long run.
> How does it work with WebSockets?
No idea. I don't develop web applications.
Where would you put Java programmers? I haven't seen FastCGI there.
> No idea. I don't develop web applications. So why do you talk about FastCGI? It is strictly for web stuff.
You haven't actually given any good examples for what makes HTTP reverse proxying bad. Things like dealing with the Host header are two-minute fixes that you only have to deal with once, but they really shouldn't even be issues in the first place. HTTP is well supported, well understood, easy to implement, and easy to scale. On the flip side, you might waste a lot of time trying to get your tech stack working with FastCGI if there isn't already existing support, and you don't benefit from any HTTP support you already have.
> Such a deployment looks terrible at best.
Again, "looks terrible" is not a valid argument against it.
Try running anything that generates absolute URLs in its HTML. And then try to make it running under two different domains, for example. A clear cookie/URL disaster, and it's all for web protocols from 2002, without talking about HSTS or CORS yet.
> Things like dealing with the Host header are two-minute fixes that you only have to deal with once,
For every f&ckin' application.
> but they really shouldn't even be issues in the first place.
They shouldn't be, I agree, in that sense that it should be impossible to get it wrong. With HTTP you don't have this and you need to deploy workarounds.
> On the flip side, you might waste a lot of time trying to get your tech stack working with FastCGI if there isn't already existing support,
Node.js may be the only offender here (I didn't bother to check). Virtually everything else that is used for web applications supports FastCGI.
> and you don't benefit from any HTTP support you already have.
Like what? What exactly is the benefit of running HTTP between frontend HTTP server and application's backend? Because the trouble with passing information about the request is a clear downside.
>> Such a deployment looks terrible at best.
> Again, "looks terrible" is not a valid argument against it.
Oh, quite the contrary. Inelegant systems or deployments usually give a death by a thousand cuts. Too many exceptions and rules and guesses to work with them.
Just as we can judge the elegance of source code, we can judge the elegance of deployments.
For some applications (those that fit within the constraints of REST - and, no, that's not all Web "apps") - you can sometimes get easy caching by dropping something like varnish somewhere between the user and the app.