Thread with 6 posts
jump to expanded post
I already knew this to some extent, but working on touchHLE has made it even more obvious to me that most documentation of APIs misses critical details. specifications are usually better, though only if there’s multiple implementations of that spec…
I think this is inevitable to some extent. the author of an API will always fail to anticipate some questions a user might have.
might be an interesting area for programming language design: how can you minimise the importance of documentation oversights?
I think Rust does better at this than Objective-C. its borrowing model gives you a lot of information about how inputs and outputs behave that I could only dream was expressed so clearly in C API documentation
also object graphs are really difficult to reason about, especially in how they relate to call graphs and inheritance graphs
I think there’ll always be a lingering doubt in the back of my mind that I’ve messed up some part of the Foundation implementation…
@hikari in rust, you are strongly encouraged to include examples in your docs, which will actually be run in the test suite to make sure they stay up to date