Organizing FIDL interfaces in the documentation on fuchsia.dev

[Curtis Galloway]

Hello FIDL folks.  Recently I've been looking into the USB driver FIDL interfaces to understand better how our USB stack works, and found it pretty hard to navigate our FIDL API reference docs on fuchsia.dev.

Currently the reference page lists all the APIs in the system in alphabetical order, without any kind of context or grouping of related interfaces.  Some are driver interfaces, some are test tools, some are libraries.  In my case, it's hard to tell which USB interfaces might be of interest to a driver writer.

For those, at least, I can fix the headerdocs to provide more context, but I was wondering if the FIDL team has considered any other explicit attributes to annotate organizational information for FIDL interfaces.  If not, perhaps we could come up with some conventions for Doxygen commands to place in headerdoc comments that would allow us to organize things on fuchsia.dev more effectively.  I've included some folks from the documentation team on this thread as well so we can discuss ideas and possible solutions.

Thanks,

--Curtis

[Curtis Galloway]

And, actually including the additional people this time. :-)

[Yifei Teng]

Hi Curtis,

Would you like to describe a hypothetical better reference page that better fits the driver needs? Agree that the current approach of listing "all the FIDLs" is probably not the best fit for all SDK consumers and application developers.

Another thing that's actionable immediately that +Mitchell Kember mentioned which I agree would help a lot was for folks to write library documentations (triple-slash comments above the library declaration), which do show up in the reference page, and is searchable using the search box. Right now only a tiny percentage of libraries have a non-empty description.

Perhaps we could also take inspirations from other documentations out there.

Wondering if the Developer Relations/Documentation team has this on their radar and has any plans that they're comfortable mentioning :)

Cheers,

Yifei

[Curtis Galloway]

Yes, when I was discussing this issue with the documentation folks they suggested consulting with the FIDL team, so I think we have a good group in this thread to discuss.

I think a good starting organization to the FIDL reference would be how interfaces are exposed to users.  A first step would be to group all those that are a part of the Fuchsia core SDK.  It's not obvious to me how to figure that out, and it might actually be a property of how you assemble the SDK.

For the remainder, it seems there are at least a few that shouldn't necessarily be in the documentation at all (test.placeholder)? so let's filter those out.  If there are others that are really only private to some internal module, either move those elsewhere or suppress them from the main developer documentation.

I started this all by looking at the USB interfaces, so for those I would group them by ones that are used by clients to communicate with USB devices vs. those intended to be implemented by drivers.  The rest are mostly of interest to those developing the Fuchsia platform USB stack so I would mark them appropriately.

This also leads to some other questions: what's the right unit of organization for platform interfaces in general below the Fuchsia platform SDK?  I think the Modular SDK RFC might be the place to answer these questions, so I will take a look there to see if that might offer some principles.

I'm guessing that the kind of organization I'm talking about here is orthogonal to the kind of attributes that FIDL expresses, so the right place to record all this might not be in FIDL itself but rather in some kind of configuration or annotation file.  That would especially make sense if some of these organizational groups depend on how you package the built software that implements the interfaces. Curious to hear your thoughts.

--Curtis

[Claudio Cherubino]

Fidldoc takes a list of IRs as input and generates the documentation for them. The way we are defining what APIs are documented is by building a given product configuration and then using the generated all_fidl_json.txt file to provide the list of IRs to process.

Currently, our builder generates documentation for two targets, "all" and "sdk". We then use Copybara to publish the sdk documentation on fuchsia.dev.

APIs like "test.placeholders" are included in the SDK target, so we should probably review what is included. We can also define another target, but it seems reasonable to me to clean up the sdk instead and document that.

As for the package organization, one option could be for the FIDL to include some tags (e.g. "usb" or "driver" or "graphics"), and then use them for grouping and search.

[Ian McKellar]

On Mon, Aug 2, 2021 at 4:39 PM 'Curtis Galloway' via fidl-dev <fidl...@fuchsia.dev> wrote:

I started this all by looking at the USB interfaces, so for those I would group them by ones that are used by clients to communicate with USB devices vs. those intended to be implemented by drivers.  The rest are mostly of interest to those developing the Fuchsia platform USB stack so I would mark them appropriately.

This also leads to some other questions: what's the right unit of organization for platform interfaces in general below the Fuchsia platform SDK?  I think the Modular SDK RFC might be the place to answer these questions, so I will take a look there to see if that might offer some principles.

I'm guessing that the kind of organization I'm talking about here is orthogonal to the kind of attributes that FIDL expresses, so the right place to record all this might not be in FIDL itself but rather in some kind of configuration or annotation file.  That would especially make sense if some of these organizational groups depend on how you package the built software that implements the interfaces. Curious to hear your thoughts.

As an engineer with a penchant for ontology I find myself wanting to solve this all by tagging FIDL libraries and interfaces. While I think there's some value in that - being able to declare in the build-system or within libraries what belongs to which part of the SDK or DDK, and maybe indicating which protocols are implemented by devices, I don't think that's enough. We also need some human authored and maintained structure. Otherwise we just go from one big alphabetical list to lots of small alphabetical lists - an improvement but not our ideal destination.

For a subsystem like USB I imagine we should have some documentation describing how the components fit together and linking to the generated API docs.

Ian

[Claudio Cherubino]

I agree with you. If we had manually curated guides with proper narratives explaining how things work together, regardless of which FIDL each comes from, then perhaps how the FIDLs are organized in the reference docs would matter less?

 

Ian