Add info about scheduler usage to user documentation

[tjallingran]

While there is info about pico_stack_init in the picoTCP User Documentation, there is no information about other core functions of the stack. I'm mainly referring to pico_stack_tick here.

As the user is always required to call pico_stack_tick, this information should be part of the User Documentation.

There is some (but not much) information about pico_stack_tick on the wiki, on the following pages:

• Development/Design Model/Modules Initialization
• Development/Design Model/Timers
• Development/Design Model/Scheduler internals
• Porting/Porting picoTCP to your favorite Operating System

[tjallingran]

Hm, perhaps integrating the user documentation into the wiki (and optionally building a pdf from the wiki) would make life easier and prevent duplicate work? Iff (parts of) the wiki and the user doc can serve the same purpose, of course.

[frederikvs]

Thanks for reporting this - we're aware that documentation is one of our weak points, it's good to get some specific examples of things we need to fix.
Quite right that pico_stack_tick should be in the user documentation.

In truth, I think that we should really have a good look at the documentation, see if we shouldn't change the whole way it's done. Building a PDF from the wiki could be one approach. Documenting the API with a doxygen-style annotation, and then extracting the PDF from that is another idea I've heard.

Next time we get some developers together, this will be one of the topics to be discussed :-)

[tjallingran]

All right, sounds good :). Thanks for the reply.

I probably can't be of much help, but if you can use input / review from the p.o.v. of someone who doesn't know much about picoTCP's internals, let me know.

If I may make a suggestion if you decide to go the doxygen route: in addition to doxygen's automatic generation of documentation for each individual function, it would be really helpful to provide an overview of the picoTCP API by explaining the relationships between the core functions. For example based on a call sequence example, perhaps presented in the form of a UML sequence diagram.