[PATCH v2] rtems: Generate <rtems/io.h>

[Gedare Bloom]

On Thu, Oct 8, 2020 at 12:51 PM Peter Dufault <dufault at hda.com> wrote:
>
> I have a minor issue with the ordering. *I haven't looked too much through earlier documents.*
>
> I don't think this has anything to do with Sebastians work, but I think it is odd that "close" comes before directives like "I/O control" (or whatever it's called) that need to be invoked when the interface is open. If the ordering is intended to correspond to normal usage, as I think Joel said, this is wrong and "close" should be at the end.
>
> If that's how the current documentation is structured we should stick with it and change it later.
>
Hi Peter,

You're right, and Sebastian has fixed it for the RTEMS Manuals.
However, this is for the generated doxygen. It is also manifesting
this seemingly arbitrary ordering in the DOxygen because of the
ordering in how different items get generated while creating the
header files.

I would like to understand how hard this might be to rectify, and
whether it is something we can defer or if we accept this as-is if it
is likely to stay mixed-up and confusing forever.

Gedare

> > On Oct 8, 2020, at 02:18 , Sebastian Huber <sebastian.huber at embedded-brains.de> wrote:
> >
> > On 07/10/2020 21:12, Gedare Bloom wrote:
> >
> >> On Wed, Oct 7, 2020 at 11:40 AM Sebastian Huber
> >> <sebastian.huber at embedded-brains.de> wrote:
> >>> On 07/10/2020 17:26, Gedare Bloom wrote:
> >>>
> >>>> Thinking about the discussion about ordering directives in the docs,
> >>>> the generated header reorders directives also. Is it also doing
> >>>> generation by alphabetical order?
> >>>>
> >>>> Should we consider using the same order as defined for the API
> >>>> documentation? I guess this would make the Doxygen consistently
> >>>> ordered wrt the docs.
> >>> This would make things a lot more complicated. For the Doxygen we have
> >>> to take also the C language into account. For example before you use a
> >>> type, it must be declared. This is done through automatic dependency
> >>> tracking and a topological sorting. Adding a manual order into this
> >>> stuff would be difficult.
> >> Yeah, maybe. The value of ordering in the headers and doxygen is
> >> probably less than in a manual. We can revisit later if we like. It
> >> shouldn't be too hard in an API header (as opposed to an
> >> implementation header with inlines) to group first the typedefs and
> >> then the function declarations. But I have no real concern about the
> >> ordering here, it was just a thought.
> >
> > Good, I added a ticket for this:
> >
> > https://devel.rtems.org/ticket/4134#ticket
> >
> > It is not on my high priority list.
> >
> > _______________________________________________
> > devel mailing list
> > devel at rtems.org
> > http://lists.rtems.org/mailman/listinfo/devel
>
> Peter
> -----------------
> Peter Dufault
> HD Associates, Inc.      Software and System Engineering
>
> This email is delivered through the public internet using protocols subject to interception and tampering.
>