Pokyny pro dokumentaci


Funkce a značky

Tato část popisuje často potřebné funkce. Chcete-li zjistit, jak fungují, podívejte se na zdrojový kód stránky.

  1. Číslované seznamy
    1. Vnořené číslované seznamy s nejméně 3 mezerami v prázdném prostoru
    2. Skutečné číslo v kódu je nepodstatné; Analýza se postará o nastavení správného čísla položky.
  • Seznamy bodů odrážek
    • Seznam vložených bodů odrážek
  • Text tučným písmem * * dvojitá hvězdička * *
  • text v kurzívěs _underscore_ nebo * jednou hvězdičkou *
  • Text highlighted as code ve větě s použitím uvozovek
  • Odkazy na stránky docs pokyny pro dokumentaci MRTK
  • Odkazy na kotvy v rámci stránky; kotvy jsou tvořeny nahrazením mezer pomlčkami a převodem na malá písmena.

V případě ukázek kódu používáme bloky se třemi značkami zaškrtnutí a jako jazyk pro zvýrazňování syntaxe zadejte CSharp :

int SampleFunction(int i)
{
   return i + 42;
}

Při zmínkách kódu ve větě use a single backtick .

TODO

Vyhněte se používání úkolů v dokumentech, a to jak v průběhu času se tyto TODO (například psaní kódu) chystá shromažďovat a informace o tom, jak se mají aktualizovat a proč se ztratí.

Pokud je nezbytně nutné přidat TODO, postupujte podle následujících kroků:

  1. Zajistěte si nový problém na GitHubu, který popisuje kontext na úkolu TODO, a poskytněte dostatek informací o tom, že další Přispěvatel bude moci pochopit a pak vyřešit úkol.
  2. Odkaz na adresu URL problému v TODO v dokumentaci.

<!--TODO https://github.com/microsoft/MixedRealityToolkit-Unity/issues/ISSUE_NUMBER_HERE : stručný BLURB problém –>

Zvýrazněné oddíly

Pokud chcete zvýraznit konkrétní body čtecího zařízení, použijte [! Poznámka] , [! Upozornění] a [! DŮLEŽITÉ] k výrobě následujících stylů. Doporučujeme používat poznámky pro obecné body a upozornění/důležité body pouze pro zvláštní relevantní případy.

Poznámka

Příklad poznámky

Upozornění

Příklad upozornění

Důležité

Příklad důležitého komentáře

Rozložení stránky

Úvod

Část napravo od názvu hlavní kapitoly by měla sloužit jako krátký úvod k čemu v této kapitole. Neudělejte to příliš dlouho, místo toho přidejte dílčí titulky. Tato možnost umožňuje propojit oddíly a uložit je jako záložky.

Hlavní tělo

Ke strukturování zbytku použijte dvě a tři úrovně nadpisů.

Mini – oddíly

Pro bloky, které by měly být vycházející, použijte tučný řádek textu. To můžeme v některých bodech nahradit čtyřmi nadpisy na čtyřech úrovních.

Oddíl viz také

Většina stránek by měla končit pomocí kapitoly nazvané Viz také. Tato kapitola je jednoduše odkazovaná seznam odkazů na stránky související s tímto tématem. Tyto odkazy se můžou v textu stránky objevit i v případě potřeby, ale to není povinné. Podobně text stránky může obsahovat odkazy na stránky, které nesouvisí s hlavním tématem, neměly by být zahrnuty v seznamu Viz také . Podívejte se na tuto stránku jako příklad pro výběr odkazů, Viz také kapitola .

Obsah (TOC)

Soubory obsahu se používají pro generování navigačních panelů v dokumentaci k MRTK github.io. Pokaždé, když se přidá nový soubor dokumentace, ujistěte se, že existuje položka pro tento soubor v jednom ze souborů TOC. yml složky dokumentace. V navigaci v dokumentaci pro vývojáře se zobrazí pouze články uvedené v souborech obsahu. Může se jednat o soubor obsahu pro každou podsložku ve složce dokumentace, která se dá propojit se stávajícím souborem obsahu a přidat ho jako dílčí oddíl do příslušné části navigace.

Styl

Styl psaní

Obecné pravidlo pro palec: Vyzkoušejte si zvukové specialisty. To obvykle znamená, že se vyhnete "konverzačnímu tónu". Zkuste se taky vyhnout tomu, abyste se vyhnuli hyperbolický a sensationalism.

  1. Nepokoušejte se (napřed) Funny.
  2. Nikdy nezapisovat ' I '
  3. Vyhněte se tomu. To může být obvykle přeformulované snadno, místo toho pomocí příkazu ' MRTK '. Příklad: "podporujeme tuto funkci" – > "MRTK podporuje tuto funkci" nebo "jsou podporovány následující funkce...".
  4. Podobně se snažte vyhnout "vašemu". Příklad: "Díky této jednoduché změně se shader stane konfigurovatelným!"- > "shadery lze nastavit s malým úsilím."
  5. Nepoužívejte "neuspořádaném fráze".
  6. Vyhněte se tomu, abyste nemuseli prodávat cokoli.
  7. Podobně se vyhnete příliš výraznému. Vykřičníky jsou potřeba jenom zřídka.

Malá

  • Pro nadpisy použijte velká a malá písmena. Dotazy. Velká písmena první písmeno a jména, ale nic jiného.
  • Pro všechno ostatní používejte regulární angličtinu. To znamená, že nemění velká slova bez velkých písmen, i když v daném kontextu drží zvláštní význam. Preferovat text kurzívou pro zvýraznění určitých slov, viz níže.
  • Pokud je odkaz vložen ve větě (což je upřednostňovaná metoda), název standardní kapitoly vždy používá velká písmena, takže se v textu přerušuje pravidlo bez velkých písmen. Proto použijte vlastní název odkazu pro opravu velkých a malých písmen. Tady je příklad odkaz na dokumentaci k ovládacímu prvku Bounds .
  • Udělejte své názvy velkými písmeny, jako je Unity.
  • Při psaní editoru Unityneměňte velká písmena "Editor".

Zvýraznění a zvýraznění

Existují dva způsoby, jak zdůraznit nebo Zvýrazňovat slova, jejich tučné písmo nebo jejich použití kurzívou. Efekt tučného textu vychází z tučného textu a je tedy možné ho snadno zaznamenat, a to i v případě, že se na stránku právě posunuje text. Tučně zvýrazněné fráze, které by si lidé měli pamatovat, je skvělé. Používejte ale tučný text zřídka, protože je obecně rušivý.

Často jeden chce buď seskupit objekt, který patří logicky společně, nebo může zvýraznit konkrétní výraz, protože má zvláštní význam. Tyto věci nemusejí vystupovat z celkového textu. Použijte text kurzívou jako odlehčenou metodu pro zvýraznění něčeho.

Podobně platí, že když se název souboru, cesta nebo položka nabídky zmiňuje v textu, raději ho nastavte na kurzívu pro logickou skupinu, aniž by to bylo rušivé.

Obecně se pokuste vyhnout zbytečnému zvýraznění textu. Speciální výrazy mohou být zvýrazněny jednou pro zajištění, že se čtenáře neopakuje, když neobsluhuje žádný účel, pokud už nefunguje a je pouze rušivý.

Zmínky o položkách nabídky

při uvedení položky nabídky, kterou by měl uživatel kliknout, je aktuální konvence: Project soubory > vytvořit > list

Vložte tolik užitečných odkazů na další stránky, ale každý odkaz pouze jednou. Předpokládejme, že čtenář klikne na všechny odkazy na stránce a zamyslete se nad tím, jak by to bylo, pokud se na stejné stránce otevírá 20 časů.

Preferovat odkazy vložené ve větě:

  • CHYBNÉ: pokyny jsou užitečné. Podrobnosti najdete v této kapitole .
  • Dobrá: pokyny jsou užitečné.

Externím odkazům se vyhnete zastaralým nebo obsahujícím obsah s copyrightem.

Při přidávání odkazu zvažte, jestli by měl být uvedený také v části Viz také. Podobně zkontrolujte, jestli se má odkaz na novou stránku přidat na stránku s odkazem.

Obrázky / snímky obrazovky

Používejte snímky obrazovky. Údržba obrázků v dokumentaci je spousta práce. Malé změny uživatelského rozhraní mohou provádět velké množství snímků obrazovky za zastaralých. Následující pravidla sníží úsilí při údržbě:

  1. Nepoužívejte snímky obrazovky pro věci, které lze popsat v textu. Zejména nikdy nepořizovat snímek obrazovky s mřížkou vlastností za jediným účelem zobrazení názvů a hodnot vlastností.
  2. Nezadáte do snímku obrazovky věci, které nejsou relevantní pro to, co se zobrazuje. Pokud se například zobrazí efekt vykreslování, vytvořte snímek obrazovky zobrazení, ale vyloučíte kolem něj jakékoli uživatelské rozhraní. V některém uživatelském rozhraní zkuste okna přesouvat tak, aby na obrázku byla jenom ta důležitá část.
  3. Při zahrnutí uživatelského rozhraní snímku obrazovky se zobrazují jenom důležité části. Když například mluvíte o tlačítkách na panelu nástrojů, vytvořte malý obrázek, který zobrazuje důležitá tlačítka panelu nástrojů, ale vyloučí všechno kolem něj.
  4. Používejte pouze obrázky, které se snadno reprodukují. To znamená, že nenakreslujte značky nebo zvýraznění na snímky obrazovky. Zaprvé, neexistují žádná konzistentní pravidla, jak by tato pravidla měla vypadat. Za druhé je reprodukování takového snímku obrazovky dalším úsilím. Místo toho popište důležité části textu. Toto pravidlo má výjimky, ale jsou vzácné.
  5. Je zřejmé, že je mnohem větší úsilí vytvořit animovaný GIF. Počítejte s tím, že budete zodpovědní za jeho opětovné vytvoření až do konce času, nebo od lidí, kteří ho vyhodí, pokud nechcete tento čas strávit.
  6. Udržujte nízký počet obrázků v článku. Často je vhodné vytvořit jeden celkový snímek obrazovky nějakého nástroje, který zobrazuje všechno, a pak popsat zbytek v textu. V případě potřeby tak můžete snímek obrazovky snadno nahradit.

Několik dalších aspektů:

  • Uživatelské rozhraní editoru pro snímky obrazovky by mělo používat světle šedý editor motivů, protože ne všichni uživatelé mají přístup k tmavému motivu a chtěli bychom zachovat co nej konzistentnější vzhled.
  • Výchozí šířka obrázku je 500 pixelů, protože se dobře zobrazuje na většině monitorů. Zkuste se od něj příliš odchýlit. Maximální šířka by měla být 800 pixelů.
  • Pro snímky obrazovky uživatelského rozhraní použijte soubory PNG.
  • Pro snímky obrazovky 3D zobrazení použijte PNG nebo JPG. Upřednostňte kvalitu před kompresním poměrem.

Seznam vlastností komponent

Při dokumentování seznamu vlastností můžete pomocí tučného textu zvýraznit název vlastnosti, pak zalomení řádků a běžný text, který je popisuje. Nepoužívejte dílčí kapitoly ani seznamy s odrážkami.

Nezapomeňte také dokončit všechny věty tečkou.

Kontrolní seznam pro dokončení stránky

  1. Ujistěte se, že jste postupli podle pokynů k tomuto dokumentu.
  2. Projděte si strukturu dokumentu a podívejte se, jestli je možné nový dokument zmínit v části Viz také na jiných stránkách.
  3. Pokud je to možné, posíťte si někoho, kdo má znalosti o tématu, a přečtěte si stránku pro technickou správnost.
  4. Have someone proof-read the page for style and formatting ( Have někdo proof-read the page for style and formatting. Může to být někdo, kdo toto téma ještě nezajme, což je také dobrý nápad získat zpětnou vazbu o tom, jak je dokumentace srozumitelná.

Zdrojová dokumentace

Dokumentace k rozhraní API se automaticky vygeneruje ze zdrojových souborů MRTK. Aby to bylo snazší, musí zdrojové soubory obsahovat následující položky:

Kromě výše uvedeného by měl být kód dobře okomentován, aby bylo možné údržbu, opravy chyb a snadné přizpůsobení.

Třídy, struktury a výčtové souhrnné bloky

Pokud se do MRTK přidává třída, struktura nebo výčet, je nutné popsat její účel. To má mít podobu souhrnného bloku nad třídou .

/// <summary>
/// AudioOccluder implements IAudioInfluencer to provide an occlusion effect.
/// </summary>

Pokud existují nějaké závislosti na úrovni třídy, měly by být zdokumentovány v bloku poznámek bezprostředně pod souhrnem.

/// <remarks>
/// Ensure that all sound emitting objects have an attached AudioInfluencerController.
/// Failing to do so will result in the desired effect not being applied to the sound.
/// </remarks>

Žádosti o schválení odeslané bez souhrnů pro třídy, struktury nebo výčty se neschválí.

Bloky vlastností, metod a souhrnů událostí

Vlastnosti, metody a události (PME) a pole se mají dokumentovat se souhrnnými bloky bez ohledu na viditelnost kódu (veřejné, soukromé, chráněné a interní). Nástroj pro generování dokumentace zodpovídá za filtrování a publikování pouze veřejných a chráněných funkcí.

POZNÁMKA: Pro metody Unity se souhrnný blok nevyžaduje (např. V chytu, spuštění nebo aktualizaci).

Ke schválení žádosti o změnu se vyžaduje dokumentace PME.

V rámci souhrnného bloku PME se vyžaduje význam a účel parametrů a vrácených dat.

/// <summary>
/// Sets the cached native cutoff frequency of the attached low pass filter.
/// </summary>
/// <param name="frequency">The new low pass filter cutoff frequency.</param>
/// <returns>The new cutoff frequency value.</returns>

Verze a závislosti úvodu funkcí

V rámci souhrnné dokumentace k rozhraní API by informace týkající se verze MRTK, ve které byla funkce zavedena, a všech závislostí, měly být zdokumentovány v bloku poznámek.

Závislosti by měly zahrnovat závislosti rozšíření nebo platformy.

/// <remarks>
/// Introduced in MRTK version: 2018.06.0
/// Minimum Unity version: 2018.0.0f1
/// Minimum Operating System: Windows 10.0.11111.0
/// Requires installation of: ImaginarySDK v2.1
/// </remarks>

Serializovaná pole

Osvědčeným postupem je použít atribut popisu Unity k poskytnutí dokumentace modulu runtime pro pole skriptu v inspektoru.

Aby možnosti konfigurace byly součástí dokumentace k rozhraní API, skripty musí v souhrnném bloku obsahovat alespoň obsah popisu.

/// <summary>
/// The quality level of the simulated audio source (ex: AM radio).
/// </summary>
[Tooltip("The quality level of the simulated audio source.")]

Výčtové hodnoty

Při definování a výčtu musí kód také dokumentovat význam hodnot výčtu pomocí souhrnného bloku. Bloky poznámek lze volitelně použít k poskytnutí dalších podrobností pro lepší pochopení.

/// <summary>
/// Full range of human hearing.
/// </summary>
/// <remarks>
/// The frequency range used is a bit wider than that of human
/// hearing. It closely resembles the range used for audio CDs.
/// </remarks>

Dokumentace s postupy

Mnoho uživatelů Mixed Reality Toolkit nemusí používat dokumentaci k rozhraní API. Tito uživatelé budou k vytváření prostředí využívat naše předem předem promyšlné, znovu použitelné předfabs a skripty.

Každá oblast funkce bude obsahovat jeden nebo více souborů markdownu (.md), které popisují poměrně vysokou úroveň toho, co je k dispozici. V závislosti na velikosti nebo složitosti dané oblasti funkcí může být potřeba dalších souborů, a to až jednoho pro každou poskytnutou funkci.

Při přidání funkce (nebo změně využití) musí být k dispozici přehledová dokumentace.

V rámci této dokumentace by měly být k dispozici oddíly s návody, včetně ilustrací, které zákazníkům pomohou s funkcí nebo konceptem v začátcích.

Dokumentace k návrhu

Mixed Reality nabízí příležitost vytvářet zcela nové světy. Součástí je pravděpodobně vytvoření vlastních prostředků pro použití s MRTK. Aby to bylo pro zákazníky co nejvíce bezproblémové, měly by komponenty poskytovat dokumentaci k návrhu popisující jakékoli formátování nebo jiné požadavky na art assety.

Tady je několik příkladů, kde může být užitečná dokumentace k návrhu:

  • Modely kurzoru
  • Prostorové mapové vizualizace
  • Soubory zvukových efektů

Tento typ dokumentace se důrazně doporučuje a může být požadován v rámci revize žádosti o schválení.

To se může nebo nemusí lišit od doporučení k návrhu na webu MICROSOFT Developer.

Poznámky k výkonu

Některé důležité funkce jsou náklady na výkon. Často bude tento kód velmi záviset na tom, jak jsou nakonfigurovány.

Například:

When using the spatial mapping component, the performance impact will increase with the level of detail requested.  
It is recommended to use the least detail possible for the desired experience.

Poznámky k výkonu se doporučují pro komponenty náročné na procesor nebo GPU a mohou být požadovány v rámci revize žádosti o stažení. Všechny příslušné poznámky k výkonu musí být součástí dokumentace k rozhraní API a přehledu.

Změny způsobující chyby

Dokumentace k rozbíjení změn se skládá ze souboru nejvyšší úrovně, který odkazuje na jednotlivé breaking-changes.md.

V oblasti funkcí breaking-changes.md soubory obsahovat seznam všech známých změn, které jsou v dané verzi známé, a také historii změn, které byly v minulosti přerušované.

Například:

Spatial sound breaking changes

2018.07.2
* Spatialization of the imaginary effect is now required.
* Management of randomized AudioClip files requires an entropy value in the manager node.

2018.07.1
No known breaking changes

2018.07.0
...

Informace obsažené v souborech na úrovni breaking-changes.md budou agregovány do poznámek k verzi pro každou novou verzi MRTK.

Všechny změny, které jsou součástí změny, musí být zdokumentované jako součást žádosti o změnu.

Nástroje pro úpravy MarkDownu

Visual Studio Code je skvělý nástroj pro úpravu souborů markdownu, které jsou součástí dokumentace MRTK.

Při psaní dokumentace se důrazně doporučuje nainstalovat taky následující dvě rozšíření:

  • rozšíření docs markdownu pro Visual Studio Code – k uvedení nabídky možností vytváření dokumentů použijte Alt + M.

  • Kontrola pravopisu kódu – slova s chybným pravopisem budou podtržena; Klikněte pravým tlačítkem na nesprávně napsané slovo, které chcete změnit, nebo ho uložte do slovníku.

Oba z nich se zabalí do balíčku pro vytváření publikovaných dokumentů společnosti Microsoft.

Viz také

MRTK

tento dokument popisuje pokyny a standardy pro dokumentaci pro Mixed Reality Toolkit (MRTK). To poskytuje Úvod k technickým aspektům psaní a generování dokumentace, k zdůraznění běžných nástrah a k popisu doporučeného stylu psaní.

Tato stránka by měla sloužit jako příklad, proto používá zamýšlené styly a nejběžnější funkce značek v dokumentaci.