Hacker News new | past | comments | ask | show | jobs | submit login

There's two types of documentation. In one, the semantics of a method allow more than one reasonable implementation. For example, if a "sqrt" function receives a negative number, it would be reasonable for it to return NaN, to throw an exception, to return a maybe monad, etc. The user has a question about the implementation, and goes to the manual to figure it out.

In the other type of documentation, nothing exists to indicate that the user should refer to the manual for more details. If I call a function "int increment_by_two(int x)", there's nothing that would indicate a special value. If the manual states "Calling 'increment_by_two' will add three to the argument.", that would certainly be unexpected. Nothing in the function description leads a user to expect that they need to read the manual for more details.




Consider applying for YC's W25 batch! Applications are open till Nov 12.

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: