Operations and Directives in Classic API Guide

[Sebastian Huber]

On 18/06/2020 00:08, Gedare Bloom wrote:

> On Wed, Jun 17, 2020 at 10:49 AM Sebastian Huber
> <sebastian.huber at embedded-brains.de> wrote:
>> Hello,
>>
>> I go currently through the entire Classic API documentation. In the
>> guide there are sections for Operations and Directives. This looks a bit
>> duplicated. Should I move the content of the Operations into the
>> Directives subsection and then delete the Operations section?
>>
> Probably Joel needs to weigh in on this one. But, I think the
> Operations part is trying to explain some of the interactions/common
> case uses of each manager, while the Directives is the detailed API
> documentation.  So, the operations section includes some things that
> may require multiple directives.  If you try to merge them, I think
> you have to make some choices about how you place these "shared"
> operation narratives.

I thought the Background section is for this "shared" operation stuff. 
But you are right we have for example:

https://docs.rtems.org/branches/master/c-user/task_manager.html#suspending-and-resuming-tasks

But also non-operations:

https://docs.rtems.org/branches/master/c-user/task_manager.html#transition-advice-for-removed-notepads

For most of the subsections there is a one-to-one correspondence to a 
directive.

I would like to remove the Operations sections and move the "shared" 
operations stuff to Background and the other subsections to the 
corresponding directive subsection in Directives.

Joel, how do you think about this?