Future of Doc Was: Re: [rtems commit] rtems: Add task get/set scheduler

[Thomas Doerfler]

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.huber at 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 at rtems.org
> http://www.rtems.org/mailman/listinfo/rtems-devel
> 


-- 
--------------------------------------------
embedded brains GmbH
Thomas Doerfler
Dornierstr. 4
D-82178 Puchheim
Germany
email: Thomas.Doerfler at 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.