Hi, good discussion. Maybe it makes sense to define what we want to write into a User's Guide, because the term is used for many different types of documents.
I agree with Sebastian that the best place for documenting each API function is doxygen, because it's source is always in sync with the real code (or as close as possible). When it comes to concepts and best practices, when it comes to "Getting stared" or "Write your first RTEMS application", doxygen might not be the best solution. So having an abstract User's Guide that is non-doxygen makes sense to me. It may include: - a Quick Start Guide chapter: "hello embedded world" in 15 minutes - more details: where do I get all the source code, the toolset, the documentation - RTEMS concepts: APIs, OS objects, threads, memory management, Link strategy, Build strategy, configuration - Best practices: Use confdefs.h, code organization, ... - debugging strategies... The User's Guide should then point to doxygen for the fizzy details. What do you think, does that make sense? wkr, Thomas Am 16.04.2014 16:08, schrieb Gedare Bloom: > On Wed, Apr 16, 2014 at 4:08 AM, Sebastian Huber > <sebastian.hu...@embedded-brains.de> wrote: >> On 2014-04-15 18:20, Joel Sherrill wrote: >>> >>> >>> On 4/15/2014 11:14 AM, Sebastian Huber wrote: >>>> >>>> On 04/15/2014 02:48 PM, Sebastian Huber wrote: >>>>> >>>>> On 2014-04-15 14:36, Joel Sherrill wrote: >>>>>> >>>>>> You added to the API and added no documentation. >>>>> >>>>> I added the documentation in Doxygen: >>>>> >>>>> http://www.rtems.org/pipermail/rtems-devel/2014-March/005901.html >>>>> >>>> Ok, since we are close to the RTEMS 4.11 release I will add texinfo >>>> documentation to all new high-level functions. After the RTEMS 4.11 >>>> release we should definitely do something against this copy and paste >>>> nightmare. >>>> >>>> Joel, what is your opinion with respect to the future documentation >>>> infrastructure of RTEMS? >>>> >>> User Guides should not be in Doxygen. >> >> >> It is possible to write user guides with Doxygen (see @page command). >> > I completely agree that we need to eliminate so much copy-paste. We > need to have a better plan for managing documentation, for user > developers and for kernel developers. I'd like to hear some more > thoughts on the subject and also see some initial requirements. > > Gedare > _______________________________________________ > rtems-devel mailing list > rtems-devel@rtems.org > http://www.rtems.org/mailman/listinfo/rtems-devel > -- -------------------------------------------- embedded brains GmbH Thomas Doerfler Dornierstr. 4 D-82178 Puchheim Germany email: thomas.doerf...@embedded-brains.de Phone: +49-89-18 94 741-12 Fax: +49-89-18 94 741-09 PGP: Public key available on request. Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG. _______________________________________________ rtems-devel mailing list rtems-devel@rtems.org http://www.rtems.org/mailman/listinfo/rtems-devel
