Hacker News Reader

Comment by _o_ | Hacker News Reader

I am quite oposite, I want example code using as much aspects of library as possible - sort of "a picture is worth a thousand words". Documentation is nice to have, but I personally consider a well written code a documentation, and it doesnt get outdated ;)

Have you checked this: https://github.com/andlabs/libui/blob/master/examples/contro... ?

View on HN

Firstly, good documentation will include example code anyway. That's part of the course of documenting.

Secondly, exams code can get outdated just as much as human documentation. I've lost count of the number of times I've gone to compile example code only to find it doesn't work because of API changes or such like. I've also had example code crash my whole machine because it effectively created a fork bomb (thanks Microsoft for that one!)

So the arguement of example code Vs documentation isn't a mutually exclusive one.

Outdated examples can be mostly avoided by building them as part of CI and if possible running. Using deprecated attribute can even detect some of the cases when example builds but doesn't match recommended way of doing things.

Sure, but that would depend on project contributors doing that as part of their process. Which leads us back to square one on 'core documentation should not be something that has to be submitted via pull request.'

In an attempt to mitigate this, you could include the examples in your testing suite, at least to see that it still compiles properly. This is sort of standardised in the flow of Go, with godoc and the testing framework. Both uses examples from the same test files, producing standalone docs and testing them(at a minimum compiling them) .

This also happens in the Rust documentation generator. The code snippets in any piece of Rust documentation are compiled and run, and the assertions found in it will be reported if they fail. They're sort-of automatically part of the test suite.

Indeed, but we are talking about the lower end of the spectrum in terms of documentation (ie the arguement of what takes priority). If someone is considerate enough to include examples as part of their testing suite then you can probably bet they'd be equally thoughtful with their documentation.

In fact the main open source project I'm working on automatically generates it's documentation to help ensure its accuracy - and I know for a fact that I'm not the only person to do this.

(Hint: I am trying to make libui's in-code documentation match the Go style, which no existing C-based documentation tool seems to do...)

The first thing I looked for (and found) was the examples directory.

Give me an example over documentation any day.

This is usually how I work. I only look for the documentation when it does not work.

Reply on news.ycombinator.com