I'll admit I haven't had time to write documentation. However, most everything follows Cocoa conventions, and the headers should be pretty readable. Absolute worst case, there's an existing app using the framework as an example. :)
You can also combine ARC and non-ARC code in one project. HNKit was written before ARC (although I still prefer manual memory management), but there's nothing keeping you from using HNKit with an ARC-based app. And unless you're modifying HNKit itself, you wouldn't ever need to see or write any retain or release calls as a client of the API. Apple did a pretty good job making ARC and non-ARC code interoperate well.
I'm happy to help with any HNKit questions — feel free to open issues on GitHub if there's anything confusing. HNKit already supports most of the things you are hoping to implement (logging in, commenting, voting), so I would hate to have all that effort duplicated. If you have any specifics about things that could be done better, I'm all ears.
Performance-wise, HNKit hasn't been optimized, but it does do parsing on a background thread. In general, a bit of extra local parsing is almost always going to be faster than additional network fetches. I haven't had any performance issues, even on older devices, so I doubt that part will be an issue at all.
Didn't mean for that to come off rude if it read that way. I haven't dug too far deep into HNKit - I was really just worried about the interplay of ARC and nonARC code and what that meant for the future of maintainability of my own codebase (really for things that go multiple classes deep, I didn't want to introduce retain cycles and the like).
I'm considering creating a branch of this with HNKit and starting to build that in to see how it plays with everything I have now.
I'll admit I haven't had time to write documentation. However, most everything follows Cocoa conventions, and the headers should be pretty readable. Absolute worst case, there's an existing app using the framework as an example. :)
You can also combine ARC and non-ARC code in one project. HNKit was written before ARC (although I still prefer manual memory management), but there's nothing keeping you from using HNKit with an ARC-based app. And unless you're modifying HNKit itself, you wouldn't ever need to see or write any retain or release calls as a client of the API. Apple did a pretty good job making ARC and non-ARC code interoperate well.
I'm happy to help with any HNKit questions — feel free to open issues on GitHub if there's anything confusing. HNKit already supports most of the things you are hoping to implement (logging in, commenting, voting), so I would hate to have all that effort duplicated. If you have any specifics about things that could be done better, I'm all ears.
Performance-wise, HNKit hasn't been optimized, but it does do parsing on a background thread. In general, a bit of extra local parsing is almost always going to be faster than additional network fetches. I haven't had any performance issues, even on older devices, so I doubt that part will be an issue at all.