search

tass-belgium / picotcp

PicoTCP is a free TCP/IP stack implementation
Other
1.18k stars 219 forks source link

Include timer API in user documentation(?) #466

Open tjallingran opened 7 years ago

tjallingran commented 7 years ago

Currently, the picoTCP User Documentation does not contain any information on timer functionality and functions, such as pico_timer_add.

The wiki does contain some information on timers (here).

Is this omission intentional (as timers are a utility, and all other API information in the User Documentation is networking-related), or should the User Documentation contain the timer API as well?

Relevant detail: pico_timer_add is used in example code given in the User Documentation (here and here).

frederikvs commented 7 years ago

Thanks for reporting this. The timers were meant for internal use only (not trying to be an OS here), and I think that's why they're not in the user documentation - they're only intended for internal developers. Of course, if that's the case, it doesn't really make much sense to have our examples reference these functions...

For now, I think the best solution is just to remove the references from the user documentation, and maybe make an explicit note somewhere on the wiki on why this isn't in the user docs.

Unless somebody can make a compelling case for putting the timers in the user documentation?

tjallingran commented 7 years ago

That makes sense.

(The reason I discovered it is that we're also using the internal timer functionality in one of the bonus exercises of the picoTCP Snake workshop. That is definitely not a compelling case for putting the timers in the user documentation ;-), but lack of documentation may be confusing to the students. Hm, thinking about it, that usage may be a bit... inappropriate, for lack of a better term. - Just thinking out loud here.)