| RFC-0183: SDK Library Documentation | |
|---|---|
| Status | Accepted |
| Areas |
|
| Description | Define requirements for reference documentation for libraries in the SDK. |
| Issues | |
| Gerrit change | |
| Authors | |
| Reviewers | |
Summary
Define the documentation requirements for libraries added to the SDK.
Motivation
Most Fuchsia code is designed to be consumed in source form. While there are sometimes overview documents in the //docs directory or README.md files in the source directory, developers are generally expected to reference the source code to discover what a given library offers and how to use it.
This approach does not scale to consumers of an operating system and all of its many supporting libraries. Developers expect to be able to reference a web page both for the general overview and lower-level usage of individual functions.
Stakeholders
Facilitator: neelsa@google.com
Reviewers: mangini@google.com, mkearney@google.com, hjfreyer@google.com, ccherubino@google.com
Consulted: sebmarchand@google.com, surajmahotra@google.com, dschuyler@google.com, jeremymanson@google.com, yifeit@google.com, computerdruid@google.com, nickvander@google.com, tmandry@google.com, theosiu@google.com, wilkinsonclay@google.com, kyol@google.com, josephry@google.com
Socialization: N/A
Design
This RFC defines a rule and location for documenting SDK libraries:
- New libraries added to the public or partner SDK must have public (or partner-restricted for the partner SDK) reference documentation.
- The documentation should be geared toward users of the SDK although it may reference fuchsia.git-only concepts if these are identified clearly.
- The documentation must be sufficient for developers to use those libraries without having to look at the source code or header files.
- The developers responsible for the library code will be responsible for generating and maintaining the content of the reference.
- Reference documentation should be generated by the //tools/docsgen infrastructure if supported in the language of the library. If unsupported, the developer can choose a format or technology as long as it has a path to being served on fuchsia.dev (email api-council@fuchsia.dev for up-to-date recommendations).
"Reference documentation" is defined for the purposes of this document as being some description of what functions and objects exist and how to use them. It assumes a good working knowledge of the system and what the general goal of the library is. This is in contrast to higher-level documentation like overviews and tutorials.
This RFC does not define:
- Requirements for higher-level documentation like overviews and tutorials.
- Detailed standards for what must be included in a good library reference.
It is expected that as library documentation evolves, future RFCs will define standards for generating, formatting, and maintaining library reference documentation.
FIDL reference docs will continue to be generated using the fidldoc infrastructure.
Implementation
The library documentation rule will apply to new libraries added to the SDK starting from the acceptance of this RFC.
The team will work over time to document the libraries already in the SDK. The mechanics of this work have not yet been defined.
Drawbacks, alternatives, and unknowns
This requirement may delay useful libraries from being added to the SDK. But without a usable reference it is likely that the full benefit of a new library can not be realized.
Avoiding defining a format for the source (like source code doc comments) or the final presentation (like what the documentation contains and how it is organized) will likely mean that initial additions will choose different approaches. We may need to reorganize these in the future. This proposal is designed to avoid complicating initial documentation work and to give the team some experience before deciding on more detailed requirements.
Prior art and references
Other operating system vendors maintain web sites documenting their system's libraries for developers. For example,
- Android Automotive Library, an example of a system library on Android.
- Uniscribe, an example of an internationalization library that comes with Microsoft Windows.
- ARKit, an example of a system library from Apple.
Many programming languages have tools for generating documentation from source code, for example, javadoc for Java and rustdoc for Rust. Doxygen is the most commonly-used C++ documentation tool, while Fuchsia team members have also contributed to clang-doc in Clang.
FIDL has existing standards and formats as defined by RFC-0043 and RFC-0055.
The Fuchsia Rust team maintains reference information for Fuchsia Rust libraries. These are hosted on a separate web site until Rust is supported in the SDK.
There are general Fuchsia documentation standards.