Dokumentacja referencyjna
W skrócie
Dział zatytułowany „W skrócie”Ta sekcja jest punktem wejścia do materiałów referencyjnych: indeksów API, kluczy konfiguracyjnych, tabel zgodności, obsługiwanego zachowania CSS oraz rejestrów zakresu obejmujących wiele pakietów.
Mapa dokumentacji referencyjnej
Dział zatytułowany „Mapa dokumentacji referencyjnej”| Dokumentacja | Na jakie pytania odpowiada |
|---|---|
| Macierz obsługi CSS | Które funkcje CSS są weryfikowane, deklarowane, częściowo obsługiwane lub nieobsługiwane przez potok HTML. |
| Indeks API integracji | Która strona API rozszerzeń obejmuje konkretny framework, mechanizm renderowania, transport oraz narzędzie do budowania. |
| Sekcje integracji | Gdzie znaleźć dokumentację referencyjną API i konfiguracji właściwą dla konkretnego pakietu. |
| Dokumentacja modułu Core | Strony dotyczące API i architektury na poziomie modułu, generowane z repozytorium core. |
Kontrakt wpisu w dokumentacji referencyjnej
Dział zatytułowany „Kontrakt wpisu w dokumentacji referencyjnej”Każdy wpis API musi odpowiadać na te same pytania:
| Pytanie | Wymagana odpowiedź |
|---|---|
| Co należy wywołać? | W pełni kwalifikowany symbol, punkt końcowy, polecenie CLI lub klucz konfiguracyjny. |
| Jakie dane wejściowe są akceptowane? | Tabela parametrów z typem, wymagalnością, wartością domyślną oraz akceptowanymi wartościami. |
| Co dzieje się domyślnie? | Zachowanie po pominięciu opcjonalnych danych wejściowych. |
| Co jest zwracane? | Typ zwracany, treść odpowiedzi, plik wyjściowy, strumień lub efekt uboczny. |
| Co może zakończyć się niepowodzeniem? | Wyjątek, błąd walidacji, status HTTP lub tryb awarii operacyjnej. |
| Jak bezpiecznie tego używać? | Uwagi dotyczące bezpieczeństwa, bezpieczeństwa wątków roboczych, limitu rozmiaru, ścieżek, limitu czasu oraz obsługi danych poufnych. |
Zasady określania zakresu dokumentacji
Dział zatytułowany „Zasady określania zakresu dokumentacji”Strony dokumentacji referencyjnej opierają się na kodzie źródłowym. Publiczne interfejsy API są dokumentowane na podstawie kodu źródłowego pakietu, plików konfiguracyjnych, testów oraz przykładów. Wewnętrzne klasy pomocnicze są dokumentowane tylko wtedy, gdy programiści aplikacji muszą rozumieć ich działanie, aby skonfigurować pakiet lub nim operować.
Gotowość do tłumaczenia
Dział zatytułowany „Gotowość do tłumaczenia”Strony dokumentacji referencyjnej preferują tabele zamiast zwartych akapitów. Każdy wiersz powinien być zrozumiały samodzielnie, ponieważ późniejsza segmentacja w formacie Extensible Localization Interchange File Format (XLIFF) podzieli treść na bloki.