mirror of
https://github.com/mollyim/webrtc.git
synced 2025-05-18 08:07:56 +01:00
0d2dc1f38f
Both WebRTC and Chromium have migrated from the "master" to the "main" branch. TBR=hta@webrtc.org Bug: None Change-Id: I2b5e6973bdd8fdc9c1bd96e2747a8a9ac2630b14 Reviewed-on: https://webrtc-review.googlesource.com/c/src/+/226080 Commit-Queue: Fanny Linderborg <linderborg@webrtc.org> Reviewed-by: Mirko Bonadei <mbonadei@webrtc.org> Cr-Commit-Position: refs/heads/master@{#34475}
71 lines
2.7 KiB
Markdown
71 lines
2.7 KiB
Markdown
# How to write WebRTC documentation
|
|
|
|
<?% config.freshness.owner = 'titovartem' %?>
|
|
<?% config.freshness.reviewed = '2021-03-01' %?>
|
|
|
|
## Audience
|
|
|
|
Engineers and tech writers who wants to contribute to WebRTC documentation
|
|
|
|
## Conceptual documentation
|
|
|
|
Conceptual documentation provides overview of APIs or systems. Examples can
|
|
be threading model of a particular module or data life cycle. Conceptual
|
|
documentation can skip some edge cases in favor of clarity. The main point
|
|
is to impart understanding.
|
|
|
|
Conceptual documentation often cannot be embedded directly within the source
|
|
code because it usually describes multiple APIs and entites, so the only
|
|
logical place to document such complex behavior is through a separate
|
|
conceptual document.
|
|
|
|
A concept document needs to be useful to both experts and novices. Moreover,
|
|
it needs to emphasize clarity, so it often needs to sacrifice completeness
|
|
and sometimes strict accuracy. That's not to say a conceptual document should
|
|
intentionally be inaccurate. It just means that is should focus more on common
|
|
usage and leave rare ones or side effects for class/function level comments.
|
|
|
|
In the WebRTC repo, conceptual documentation is located in `g3doc` subfolders
|
|
of related components. To add a new document for the component `Foo` find a
|
|
`g3doc` subfolder for this component and create a `.md` file there with
|
|
desired documentation. If there is no `g3doc` subfolder, create a new one;
|
|
|
|
When you want to specify a link from one page to another - use the absolute
|
|
path:
|
|
|
|
```
|
|
[My document](/module/g3doc/my_document.md)
|
|
```
|
|
|
|
If you are a Googler also please specify an owner, who will be responsible for
|
|
keeping this documentation updated, by adding the next lines at the beginning
|
|
of your `.md` file immediately after page title:
|
|
|
|
```markdown
|
|
<?\% config.freshness.owner = '<user name>' %?>
|
|
<?\% config.freshness.reviewed = '<last review date in format yyyy-mm-dd>' %?>
|
|
```
|
|
|
|
If you want to configure the owner for all pages under a directory, create a
|
|
`g3doc.lua` file in that directory with the content:
|
|
|
|
```lua
|
|
config = super()
|
|
config.freshness.owner = '<user name>'
|
|
return config
|
|
```
|
|
|
|
After the document is ready you should add it into `/g3doc/sitemap.md`, so it
|
|
will be discoverable by others.
|
|
|
|
### Documentation format
|
|
|
|
The documentation is written in GitHub Markdown
|
|
([spec](https://github.github.com/gfm/#:~:text=GitHub%20Flavored%20Markdown%2C%20often%20shortened,a%20strict%20superset%20of%20CommonMark.)).
|
|
|
|
## Class/function level comments
|
|
|
|
Documentation of specific classes and function APIs and their usage, including
|
|
their purpose, is embedded in the .h files defining that API. See
|
|
[C++ style guide](https://chromium.googlesource.com/chromium/src/+/main/styleguide/c++/c++.md)
|
|
for pointers on how to write API documentatin in .h files.
|