4 ms·
> I do not share your experience, because in my experience the auto-generated docs will be kept in sync with the code/API while a separate specification will be
by protomikron 7y ago
> I do not share your experience, because in my experience the auto-generated docs will be kept in sync with the code/API while a separate specification will become outdated over time.
Does it? You can just alter the code and forget to alter the documentation above the functions/methods, so I don't think there is much of a difference. And wrong documentation is worse then no documentation.
You have to write your documentation, keep it up to date and take it seriously. I would argue, if you have auto-documentation you are more likely to miss that, because you have some kind of documentation somehow - irregardless if it's actually useful.
- 725686 7y ago"Does it? You can just alter the code and forget to alter the documentation above the functions/methods" Yes you can forget, but the barrier is much, much, much lower than having to modify a document god knows where.
- ses1984 7y agoI've used swagger with java and golang and both of them generate docs directly from the code, no comments needed.
- protomikron 7y agoBut what's the point then? If there's a tool, that can make "documentation" out of source code, I can just look at the source code?
- kazagistar 7y agoMostly it collates all your endpoints more easily, generates clients for different languages, genearates an online documentation and test page that makes your service self describing, and can be published out to third parties that dont have access to your code.
- deleted 7y ago[deleted]
- teknopaul 7y agoPresumption that all code is open source. The war is won :-)
- curryst 7y agoThe tool parses out the bits that you're interested in. If you want to know what year the proverbial apple fell on Isaac Newton's head, you can get a biography and start reading, or you can Google and let the machine filter out the irrelevant bits. If I'm looking at documentation, I want the inputs and outputs and a brief description of what it does. I care very little about the implementation, or I would write my own.
- minxomat 7y agoFor abstract descriptions of what the code does, sure. But for small things like documenting the purpose of arguments, an IDE should warn about changes that are not reflected in the doc comment (type or a new arg altogether). IntelliJ IDEs are pretty good at that. Rust for example also warns about code included in the doc comments example section which is invalid.
- steveklabnik 7y agoWith Rust, we help mitigate this by running code examples in API documentation as tests. That doesn't stop people from opting out, and it doesn't solve every problem, but it's still quite useful!
- mdtusz 7y agoI'm sure you know because you're Steve Klabnik, but for other readers: you can enforce documentation for public items in a crate by adding `#![deny(missing_docs)]` to the `lib.rs` file. Then it just takes some self-control and gold code reviews to make sure you're writing good documentation rather than just short stubs to silence the error.
- steveklabnik 7y agoYou’d think, but I have certainly committed (in both the colloquial and git sense) a dummy /// TODO comment to silence this warning... oops
- joshmarlow 7y agoI'm going to hijack this thread to recommend Rust Skeptic - https://github.com/budziq/rust-skeptic https://github.com/budziq/rust-skeptic It checks for rust snippets in markdown files and attempts to build them when you run `cargo test`. It helps keep docs and code in sync.