2 ms·

> It's perfectly fine to have big blocks of documentation comments right in the code, and to be consumed there. If you need to read the source code to use a li

> It's perfectly fine to have big blocks of documentation comments right in the code, and to be consumed there. If you need to read the source code to use a library, something is wrong with that library. (On the other hands it is fine to document local functions, but it doesn't need to be a verbose documentation comment.)

jgtrosh 7y ago
Quite the opposite, a library can be understood fast and in depth when the code and its comments are readable directly, skipping the indirection layer of any external documentation.
- lifthrasiir 7y ago
  "in depth" is probably correct, but "fast" depends. I tend to classify libraries into two classes, something I can obviously make but I don't have to, and something I would have to try hard (or even be impossible) to make it. You can't quickly understand the second class of libraries by reading the code. If you need a concrete example, take miniSAT [1] as one. [1] https://github.com/niklasso/minisat/blob/master/minisat/core/Solver.cc https://github.com/niklasso/minisat/blob/master/minisat/core...
flohofwoe 7y ago
I'm thinking of examples like this: https://github.com/nothings/stb/blob/master/stb_image.h https://github.com/nothings/stb/blob/master/stb_image.h It's a complete image loader library in a single header. This header contains everything I need to use that library: the entire documentation, the license, public API declarations and finally the implementation source code. I can read this file from top to bottom to know every little detail about this library, or I can stop somewhere inbetween (for instance when I only want to know how to use the library and what the API looks like, but I'm not interested in the implementation details).
- lifthrasiir 7y ago
  First, I consider a single header library as a symptom from the lack of fine package managers for C and not as a feature. Such a form should not have been a norm at all. Also note that stb_image is extremely stateless. The documentation is not a must for stateless APIs because it is relatively easier to infer from the signature (of course you need to learn the convention, for example, to see that `int x, int y` etc. are out parameters and should not be NULL though). But many other libraries need states, and a proper documentation is required.

jgtrosh 7y ago

Quite the opposite, a library can be understood fast and in depth when the code and its comments are readable directly, skipping the indirection layer of any external documentation.

lifthrasiir 7y ago
"in depth" is probably correct, but "fast" depends. I tend to classify libraries into two classes, something I can obviously make but I don't have to, and something I would have to try hard (or even be impossible) to make it. You can't quickly understand the second class of libraries by reading the code. If you need a concrete example, take miniSAT [1] as one. [1] https://github.com/niklasso/minisat/blob/master/minisat/core/Solver.cc https://github.com/niklasso/minisat/blob/master/minisat/core...

flohofwoe 7y ago

I'm thinking of examples like this: https://github.com/nothings/stb/blob/master/stb_image.h https://github.com/nothings/stb/blob/master/stb_image.h It's a complete image loader library in a single header. This header contains everything I need to use that library: the entire documentation, the license, public API declarations and finally the implementation source code. I can read this file from top to bottom to know every little detail about this library, or I can stop somewhere inbetween (for instance when I only want to know how to use the library and what the API looks like, but I'm not interested in the implementation details).

lifthrasiir 7y ago
First, I consider a single header library as a symptom from the lack of fine package managers for C and not as a feature. Such a form should not have been a norm at all. Also note that stb_image is extremely stateless. The documentation is not a must for stateless APIs because it is relatively easier to infer from the signature (of course you need to learn the convention, for example, to see that `int x, int y` etc. are out parameters and should not be NULL though). But many other libraries need states, and a proper documentation is required.