4 ms·
Why "require" documentation comment blocks to be parsed by external tools and read elsewhere? It's perfectly fine to have big blocks of documentation comments r
by flohofwoe 7y ago
Why "require" documentation comment blocks to be parsed by external tools and read elsewhere? It's perfectly fine to have big blocks of documentation comments right in the code, and to be consumed there.
The current "fashion" of making comments as unreadable as possible in most syntax highlighter themes is indeed my main gripe with them.
Comments don't have to particularly stick out, but it would at least help to make them as readable as the actual source code.
- rightbyte 7y agoYe. Reading eg. Javadoc verbatim is awefull. There are nice doc generators that allow natural language with markup only for special attributes.
- lifthrasiir 7y ago> 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 agoQuite 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 agoI'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 agoFirst, 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.