News for hackers. Stuff that matters.
Re:Four kinds of documentation by ses1984 on Friday October 18, 2019 @09:44AM (#21291283)
I've used swagger with java and golang and both of them generate docs directly from the code, no comments needed.
Re:Four kinds of documentation by protomikron on Friday October 18, 2019 @09:46AM (#21291296)
But 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?
Re:Four kinds of documentation by kazagistar on Friday October 18, 2019 @10:06AM (#21291440)
Mostly 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.
Re:Four kinds of documentation by curryst on Friday October 18, 2019 @02:18PM (#21293783)
The 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.

Re:Four kinds of documentation by teknopaul on Friday October 18, 2019 @10:44AM (#21291789)
Presumption that all code is open source. The war is won :-)