TL;DR We need to standardize the methods we use to describe and document AGL APIs. I propose a site model ourselves after and the steps we need to get there. The SAT will discuss this on Thursday and in person in two weeks.
Currently the documentation site has a general landing page for all APIs. [1]. If you jump to the link of a particular API on the page you get the git directory of the API. From there you may or may not find useful documentation and the documentation methodology is not standardized across the project.
What we would like to see is something like we see in the Fuchsia project documentation site. [2]. Clicking on one of the APIs [3] you can clearly see where the documentation came from (a FIDL file) and you get a nice human readable description of the API with optional explanations for each API. In looking at the Fuchsia source code, the API documentation that is rendered on the web site resides with SDK. There are some FIDL objects or calls in the target source code that matches the FIDL in the SDK. There looks to be some kind of generation step to create the FIDL files.
I do not know how we get from where we are today to where we need to be. I would put forth that we need a human readable version of our APIs that is similar to the Fuchsia project.
The steps AGL needs to take to this level of documentation includes:
a) Agree upon a way to extract the API information from the existing into an AGL documentation file (not FIDL since it is more of an overall IDL and code generator).
b) Get someone to write the initial version of a tool that does the extraction and places the documentation in an agreed upon place for the doc site. However this done we need to ensure there is a tie between the actual source code and the documentation.
c) Finish the documentation for all APIs listed on the documentation site.
The good news is that I think we have lot of the pieces in place to get this done quickly and some resources to help us get there. I will add this topic to the SAT call on Thursday and in person in two weeks.
Regards,
Walt
[3] https://fuchsia.dev/reference/fidl/fuchsia.media.audio
--
_______________________________________________ automotive-discussions mailing list automotive-discussions@xxxxxxxxxxxxxxxxxxxxxxxxx https://lists.linuxfoundation.org/mailman/listinfo/automotive-discussions
