Dokumentowanie kodu przy użyciu kodu XML (Visual Basic)

  • Artykuł

W języku Visual Basic możesz udokumentować kod przy użyciu kodu XML.

Komentarze dokumentacji XML

Język Visual Basic umożliwia łatwe tworzenie dokumentacji XML dla projektów. Możesz automatycznie wygenerować szkielet XML dla typów i elementów członkowskich, a następnie podać podsumowania, opisową dokumentację dla każdego parametru i inne uwagi. W przypadku odpowiedniej konfiguracji dokumentacja XML jest automatycznie emitowana do pliku XML o tej samej nazwie pliku głównego co projekt. Aby uzyskać informacje na temat konfigurowania generowania pliku dokumentacji XML, zobacz opcję -doc kompilatora i właściwość GenerateDocumentationFile MSBuild.

Plik XML może być używany lub w inny sposób manipulować jako XML. Ten plik znajduje się w tym samym katalogu co plik wyjściowy .exe lub .dll projektu.

Dokumentacja XML rozpoczyna się od '''. Przetwarzanie tych komentarzy ma pewne ograniczenia:

  • Dokumentacja musi być poprawnie sformułowanym kodem XML. Jeśli kod XML nie jest poprawnie sformułowany, zostanie wygenerowane ostrzeżenie, a plik dokumentacji zawiera komentarz z informacją o napotkaniu błędu.

  • Deweloperzy mogą tworzyć własny zestaw tagów. Istnieje zalecany zestaw tagów (zobacz Tagi komentarzy XML). Niektóre z zalecanych tagów mają specjalne znaczenie:

    • Tag <param> służy do opisywania parametrów. Jeśli jest używany, kompilator sprawdzi, czy parametr istnieje i czy wszystkie parametry zostały opisane w dokumentacji. Jeśli weryfikacja zakończy się niepowodzeniem, kompilator wyświetla ostrzeżenie.

    • Atrybut cref można dołączyć do dowolnego tagu, aby podać odwołanie do elementu kodu. Kompilator sprawdza, czy ten element kodu istnieje. Jeśli weryfikacja zakończy się niepowodzeniem, kompilator wyświetla ostrzeżenie. Kompilator uwzględnia również wszelkie Imports instrukcje podczas wyszukiwania typu opisanego w atrybucie cref .

    • Tag <podsumowania> jest używany przez funkcję IntelliSense w programie Visual Studio do wyświetlania dodatkowych informacji o typie lub elemencie członkowskim.

Aby uzyskać szczegółowe informacje na temat tworzenia pliku XML z komentarzami do dokumentacji, zobacz następujące tematy:

Zobacz też