docs/contribute/governance/rfcs/0183_sdk_library_documentation.md

<!-- mdformat off(templates not supported) -->
{% set rfcid = "RFC-0183" %}
{% include "docs/contribute/governance/rfcs/_common/_rfc_header.md" %}
# {{ rfc.name }}: {{ rfc.title }}
{# 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 #}
<!-- SET the `rfcid` VAR ABOVE. DO NOT EDIT ANYTHING ELSE ABOVE THIS LINE. -->

<!-- mdformat on -->

## 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,
pineapple@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](https://developer.android.com/reference/android/car/packages),
    an example of a system library on Android.
  * [Uniscribe](https://docs.microsoft.com/en-us/windows/win32/intl/uniscribe-reference),
    an example of an internationalization library that comes with Microsoft
    Windows.
  * [ARKit](https://developer.apple.com/documentation/arkit), an example of a
    system library from Apple.

Many programming languages have tools for generating documentation from source
code, for example,
[javadoc](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html)
for Java and [rustdoc](https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html)
for Rust. [Doxygen](https://doxygen.nl/) is the most commonly-used C++
documentation tool, while Fuchsia team members have also contributed to
[clang-doc](https://clang.llvm.org/extra/clang-doc.html) in Clang.

FIDL has existing standards and formats as defined by
[RFC-0043](0043_documentation_comment_format.md) and
[RFC-0055](0055_documentation_comments.md).

The Fuchsia Rust team maintains reference information for [Fuchsia Rust
libraries](https://fuchsia-docs.firebaseapp.com/rust/). These are hosted on a
separate web site until Rust is supported in the SDK.

There are general [Fuchsia documentation
standards](/docs/contribute/docs/documentation-standards.md).