Jak dodać nazwę polecenia cmdlet i streszczenie do tematu pomocy dotyczącego polecenia cmdlet

W tej sekcji opisano sposób dodawania zawartości wyświetlanej w sekcjach NAME i SYNOPSIS pomocy dotyczącej polecenia cmdlet. W pliku Pomocy ta zawartość jest dodawana do węzła Polecenia dla każdego polecenia cmdlet.

Uwaga

Aby uzyskać pełny widok pliku Pomocy, otwórz jeden z plików znajdujących dll-Help.xml się w katalogu instalacyjnym programu PowerShell. Na przykład plik Microsoft.PowerShell.Commands.Management.dll-Help.xml zawiera zawartość kilku poleceń cmdlet programu PowerShell.

Aby dodać nazwę polecenia cmdlet i synopsis

  • Pomoc polecenia cmdlet może wyświetlić dwa opisy dla polecenia cmdlet. Pierwszy opis to krótki opis, który jest określany jako synopsis. Drugi opis to bardziej szczegółowy opis, który został omówiony w temacie pomocy Dodawanie szczegółowego opisu do polecenia cmdlet. Oba te opisy powinny być napisane jako pojedynczy akapit.

  • W synopsis nie powtarzaj nazwy polecenia cmdlet. Informowanie użytkownika, że Get-Server polecenie cmdlet pobiera serwer, jest krótkie, ale nie zawiera informacji. Zamiast tego użyj synonimów i dodaj szczegóły do opisu.

    Przykład: "Pobiera obiekt, który reprezentuje komputer lokalny lub zdalny".

  • W synopsie użyj prostych czasowników, takich jak "get", "create" i "change". Unikaj używania wyrazów "set", ponieważ są to niejasne i wymyślne wyrazy, takie jak "modify".

    Przykład: "Pobiera informacje o podpisie Authenticode w pliku".

  • Pisz w aktywnym głosie. Na przykład "Użyj obiektu TimeSpan..." jest znacznie bardziej czytelny niż "można użyć obiektu TimeSpan..."

  • Unikaj czasownika "display" podczas opisywania polecenia cmdlet, które pobrać obiekty. Chociaż Windows PowerShell wyświetla dane polecenia cmdlet, ważne jest, aby wprowadzić użytkowników do koncepcji, że polecenie cmdlet zwraca .NET Framework obiektów, których dane mogą nie być wyświetlane. Jeśli wyróżnisz wyświetlanie, użytkownik może nie zdawać sobie sprawy, że polecenie cmdlet mogło zwrócić wiele innych przydatnych właściwości i metod, które nie są wyświetlane.

Zobacz też

Windows PowerShell SDK