{% set rfcid = “RFC-0183” %} {% include “docs/contribute/governance/rfcs/_common/_rfc_header.md” %}
{# Fuchsia RFCs use templates to display various fields from _rfcs.yaml. View the #} {# fully rendered RFCs at https://fuchsia.dev/fuchsia-src/contribute/governance/rfcs #}
Define the documentation requirements for libraries added to the SDK.
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.
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
This RFC defines a rule and location for documenting SDK libraries:
“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:
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.
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.
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.
Other operating system vendors maintain web sites documenting their system's libraries for developers. For example,
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.