Parancsmag nevének és összefoglalójának hozzáadása egy parancsmagokkal kapcsolatos súgótémakörhöz

  • Cikk

Ez a szakasz a parancsmag súgója NAME és SYNOPSIS szakaszában megjelenő tartalmak hozzáadását ismerteti. A súgófájlban ez a tartalom minden parancsmaghoz hozzá lesz adva a Parancs csomóponthoz.

Megjegyzés

A súgófájl teljes megtekintéséhez nyissa meg a PowerShell telepítési könyvtárában dll-Help.xml található fájlok valamelyikét. A fájl például több PowerShell-parancsmag tartalmát Microsoft.PowerShell.Commands.Management.dll-Help.xml is tartalmazza.

A parancsmag nevének és az áttekintés hozzáadásához

  • A parancsmag súgója két leírást tud megjeleníteni a parancsmaghoz. Az első leírás egy rövid leírás, más néven a szinopsis. A második leírás egy részletesebb leírás, amely a Részletes leírás hozzáadása parancsmagokkal kapcsolatos súgótémakörben található. Mindkét leírást egyetlen bekezdésben kell megírni.

  • A szinopsiában ne ismételje meg a parancsmag nevét. A felhasználó tájékoztatása arról, hogy a parancsmag egy kiszolgálót Get-Server kap, rövid, de nem informatív. Ehelyett használjon szinonimákat, és adjon hozzá részleteket a leíráshoz.

    Például: "Lekért egy objektumot, amely egy helyi vagy távoli számítógépet képvisel."

  • Használjon olyan egyszerű műveleteket a szinopsiában, mint a "get", a "create" és a "change". Kerülje a "set" (beállítás) használatának mellőzését, mert az nem egyértelmű, és elegáns szavakat , például "módosítás".

    Például: "Lekért információ az Authenticode-aláírásról egy fájlban."

  • Írás aktív hangon. Például: "Használja a TimeSpan objektumot..." sokkal egyértelműbb, mint "a TimeSpan objektum használható..."

  • Ne jelenítse meg a "display" (megjelenítés) igét az objektumokat lekért parancsmagok leírásakor. Bár Windows PowerShell megjeleníti a parancsmagadatokat, fontos bevezetni azt a fogalmat, hogy a parancsmag olyan .NET-keretrendszer objektumokat ad vissza, amelyeknek az adatai esetleg nem jelennek meg. Ha kiemeli a megjelenítést, előfordulhat, hogy a felhasználó nem veszi észre, hogy a parancsmag számos más hasznos tulajdonságot és metódust is visszaadott, amelyek nem jelennek meg.

Lásd még:

Windows PowerShell SDK