The API had the exact same problems then... unanswered questions, confusing documentation, complex code examples. Something that seemed so simple--post a link to someone's wall, with their permission--turned into a multi-day codefest. But I finally got it working!
Until one day a few months later, when the API changed without warning. And that's what I think the biggest problem with the FB API is... they (at least back in the day) change it constantly, without much warning, and don't update documentation in a sane way. It's impossible to build once and forget.
I finally got a complaint from a user one day that the FB integration wasn't working. When I went in to check the code, I found that FB had almost completely changed their JS libraries and made significant API changes. Instead of going through that hell again, I just removed the feature.