Electronics > Microcontrollers

Parsing UART packets / state machines / packed structs

<< < (11/13) > >>

Siwastaja:

--- Quote from: nctnico on December 08, 2022, 09:47:32 am ---I deeply loath 'documentation' made using Doxygen because the output just lacks the one important thing: why is the code the way it is and what are the relations of functions?

--- End quote ---

Exactly, Doxygen is cancerous. The purpose is to let the programmers be lazy, and give the impression of having documentation to the higher-ups who just look at it and say "looks nice, 'have nice documentation' checkbox marked".

Just worked with Eclipse PAHO embedded mqtt client, and the Doxygen documentation is just... none:

--- Code: ---/** MQTT Subscribe - send an MQTT subscribe packet and wait for suback before returning.
 *  @param client - the client object to use
 *  @param topicFilter - the topic filter to subscribe to
 *  @param message - the message to send
 *  @return success code
 */
DLLExport int MQTTSubscribe(MQTTClient* client, const char* topicFilter, enum QoS, messageHandler);

--- End code ---

This is nearly useless, literally the only useful information not conveyed already by the names is "wait for suback before returning".

For example, crucial piece of information in any C library where pointers are passed to functions which modify the internal state of the library is, who is responsible of the lifetime (memory allocation) of the object? Many other similar looking functions internally do memcpy on the pointer to some internal buffer, but this particular piece of crap just copies topicFilter pointer to be used later, so you can't generate the filter string in stack and just call the function, or everything breaks down in mysterious ways. Both are valid strategies but you have to tell the user which it is, and it would have been literally 15 seconds of typing to tell me that.

Further, you can see they copy-pasted the description from some other function, so not only the documentation is lacking, it's wrong, too. Bright side is, as this documentation is useless anyway, no one reads it so no one notices the mistake, and managers are happy about the nice-looking "API documentation".

We programmers - we just look at the code and figure out what is does, how it does it - and finally, try to guess why. And when we can't figure out why PAHO, for example, checks if return codes are < 0 (errors) and then replace them with fixed -1 to hide the original error code and just tell the application about a generic error, we come into conclusion there is no sensible reason to do so, and fix the crap, removing those extra steps and make error codes propagate again.

SiliconWizard:
People often use Doxygen or similar because they were asked to produce documentation, and documentation is notoriously hard and annoying to produce. So they're looking for the easy way out just to make their bosses happy.

And yes, a few comments where it really matters, and well written code with clear structure and decent type/variable/function naming is worth 10x times that, but since it actually requires competent people to be able to judge, it doesn't work that well in the corporate world.

NorthGuy:
Documentation may be good or bad, but it doesn't matter how it's written. It's possible to write good documentation with Doxygen, as it is possible to do the same without Doxygen.

A software engeineer is the best person to write documentation, but most don't want to do that. Furthermore, the employers often don't want to pay them for that. Therefore documentation is usually written by technical writers who do not have a clue what they're writing about. This is not much better than phony Doxygen comments.

ledtester:
On the topic of documentation, here is one of the main developers of the Haskell compiler talking about a note system that has proven to be a boon to maintaining the codebase over its lifetime (which now exceeds 20 years):

Past and Present of Haskell – Interview with Simon Peyton Jones
https://youtu.be/4RuLzL_q0zs?t=44m9s

(segment starts at 44:09)

DiTBho:

--- Quote from: SiliconWizard on December 08, 2022, 06:32:56 pm ---People often use Doxygen or similar because they were asked to produce documentation, and documentation is notoriously hard and annoying to produce. So they're looking for the easy way out just to make their bosses happy.

--- End quote ---

"Stood" is the best tool-way to produce both code skeleton and doc by design.
Kind of compromise.

Navigation

[0] Message Index

[#] Next page

[*] Previous page