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

Reply via email to