4 ms·
It depends on your definition. API is application programming interface, which means that if your product doesn't intend for it's internals to be called or it i
by lighthawk 11y ago
It depends on your definition. API is application programming interface, which means that if your product doesn't intend for it's internals to be called or it is a DSL, etc. you don't necessarily need to have formal API docs- you just need usage docs. If it is a C, C++, Java library, then yes, you probably want API docs/Javadocs.
- jharger 11y agoThis is just my opinion, but if you want any other contributors besides yourself, I think you definitely want API docs. Just because it's not exposed to the public doesn't mean nobody cares what a function/class does. If it has a DSL, or any sort of scripting, as a user you damn well want it to have API docs. It's super frustrating to have a use case the author didn't think about, and you have to figure it out via trial and error because the author didn't think it'd be worth spending a few hours documenting what each thing is supposed to do. Don't think that just because some projects were successful without API documentation, maybe because they served a particular niche, that means you can just ignore documentation because you feel it's not necessary.
- lighthawk 11y agoI think you and I have different idea of what API docs are. I think that good documentation for usage is a great idea, but not all projects need formal API docs, because not all of them intend for the classes in their project to be used as a library. I agree with you that if your code intends to be used as a library, you should provide API docs. And, if you expose a service then you should probably provide API service documentation with examples. I'd add also that usage examples can sometimes go much further than API docs to clarifying things.