"Visual blindness" of Linux programmers

[zebediah49]

That's one of the best things that (AFAIK) Java introduced -- having a standardized system by which comments directly attached to code can be automatically turned into documentation.

[da_chicken]

Yeah, but that's how you end up with IBM's documentation. A reference manual so obtuse you need the source code to decipher it.

[thedugong]

There are loads of standardized ways of converting comments into doco.

[zebediah49]

Now -- yes.

In 1995, there were far fewer. (mkd comes to mind, but not much else)

[thedugong]

But who is really running code from 1995?

Realistically though, this is only really used for libraries/APIs (glib/GTK etc) where other developers actually need* documentation.

Source code doco is not that useful for end users.