One of my pet peeves: documentation that doesn't say anything. Methods (and callbacks) are listed by name with some thrifty description of argument. But none of the important stuff is ever there: is it reentrant? stateless? Who owns each non-scalar argument? Can it be invoked from user space? installable driver? kernel driver? Signal handler? Does it have latency constraints? Can I use it from a different thread than it was constructed under? Is it protected during thread death? Is it atomic vs what other methods? What other apis are allowed/forbidden when writing a callback?
As an embedded programmer, I end up reading library source most of the time trying to find these answers. And if it isn't open, then I have to black-box test or lard calls up with semaphores which might not be necessary. The state of API documentation is in the stone age.
As an embedded programmer, I end up reading library source most of the time trying to find these answers. And if it isn't open, then I have to black-box test or lard calls up with semaphores which might not be necessary. The state of API documentation is in the stone age.