[Sunspots]

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) .

[tomsmeding]

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.

[laumars]

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.

[andlabs]

(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...)