Kristoffer,
Thanks for your feedback. You ask what parts of the documentation need work,
and let me just show you how many stumbling blocks there are by showing you
where I am now:
Your fix of removing the second argument of that constructor doesn't get me
very far. Now I need to know what "yourServerValidateURI" is, and further in
the docs it explains it, but that explanation includes this sentence:
"Note that the 2 the protocol for the 2 first resource are defined in the
OAuth2 specfication while the third is not (TODO! Describe our validation
protocol)"
Honestly, I can't follow text like that. It doesn't make the slightest bit of
sense (even in context). I really just gave up on the written docs at that
point.
Instead, I tried the complete downloadable example code, but it doesn't work.
First, it was hard figure out how to compile and run it (I am not a maven
expert), but once I got past those hurdles I pointed my browser to
localhost:8095 and got a 404. So I had to look at the code, with no
understanding of the overall structure (because there is no relationship
between the example and what's on the documentation page that I can discern),
and only moderate experience with restlet, and tried to figure out what the
entry points might be. Once I did that, I got exceptions referring to this
mellowtech.org thing. Searching through the code, there are no comments
suggesting what that is or how I might need to change mellowtech.org to my own
hostname to get things to work. Nothing. When I visit mellowtech.org with my
browser, there's no mention of a service or anything about how to do oauth. Why
is sample code relying on this? WTF?
So I tried changing mellowtech.org to localhost and got another error (posted
separately).
Honestly, this all seems pretty hopeless to me because: 1. I don't even know
what to try next. 2. The official examples provided by the restlet team don't
work!
I believe the example should 1. work and 2. be self contained. If they
absolutely must rely on a third party service, that reliance must be
documented, which it's not. If that can't happen, then the all the docs in the
world will still leave users frustrated, because many many many users go
straight to sample code. Fix that, and the docs just need to explain how the
code works, with snippets taken from the live working code, rather than just
stuff made up on the spot for the sake of the docs.
I hope that helps clarify where I am coming from.
bjorn
-----------------------------
Bjorn Roche
http://www.xonami.com
Audio Collaboration
http://blog.bjornroche.com
------------------------------------------------------
http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=3011301
