Dokumentacja XML Komentarze z interfejsami i implementującymi klasami

Question

Dokumentuję zespół za pomocą XML Documentation Comments, z którego zostanie utworzony plik chm przy użyciu Sandcastle.

Mój zestaw zawiera różne interfejsy, z których każdy jest implementowany przez jedną klasę (w moim scenariuszu są to usługi WCF).

Dodałem dokumentację do interfejsów, czy jest jakiś sposób, aby automatycznie udokumentować odpowiednie metody na ćwiczeniach?

Answer 1

Wydaje się, że nie ma żadnego poparcia dla takiej autodokumentacji w Sandcastle. Model Sandcastle Help File Builder implementuje jednak niestandardowy znacznik inheritdoc.

Z witryny SHFB:

Pomoc jest wliczone w < inheritdoc/> tag, który pozwala na dokumentacji dziedziczą z bazy typy/członków. Jest to zaimplementowane za pomocą niezależnego narzędzia o numerze , dzięki czemu może być również używane przez inne narzędzia innych firm i skrypty budowania . To narzędzie zapewnia funkcje , wykraczające poza te znalezione w komponencie budowlanym dostarczonym z Sandcastle.

Druga aktualizacja: według this workitem, w "wsparcie" dla inheritdoc Sandcastle jest przez narzędzie SHFB. Podsumowując, przypuszczam, że SHFB rozwiązuje twój problem.

Answer 2

Narzędzie takie jak GhostDoc może wygenerować dokumentację na temat klas implementacji, gdy używasz jej skrótu klawiaturowego. Nie jest to całkowicie automatyczne, ale może pomóc w zapobieganiu wklejaniu zbyt wielu kopii.

Być może można zautomatyzować za pomocą skryptu.

Answer 3

AtomineerUtils automatycznie generuje komentarze dla ciebie, i odbiera istniejącą dokumentację od przeciążenia i przesłoniętej klasy bazowej, oszczędzając mnóstwo kłopotów w duplikowaniu informacji tam, gdzie jest to potrzebne.

http://www.atomineer.com/AtomineerUtils.html

Answer 4

mam lepszą odpowiedź: FiXml.

Klonowanie uwag GhostDoc \ AtomineerUtils pewnością działa podejście, ale ma istotne wady, np .:

• Gdy oryginał komentarz zostanie zmieniony (co często zdarza się w trakcie rozwoju), jego klon nie jest.
• Produkujesz ogromną liczbę duplikatów. Jeśli używasz narzędzi do analizy kodu źródłowego (np. Duplicate Finder w Team City), będzie to znajdowanie głównie Twoich komentarzy.

Jak już wspomniano, istnieje <inheritdoc> tag w Sandcastle, ale ma kilka wad w porównaniu do FiXml:

• Sandcastle produkuje skompilowane pliki pomocy HTML - to nie zmienia .xml plików zawierające wyodrębnione komentarze XML. Ale te pliki są używane przez wiele narzędzi, takich jak: .NET Reflector i przeglądarka klas \ IntelliSense w Visual Studio .NET. Więc jeśli użyjesz tylko Sandcastle, nie zobaczysz tam odziedziczonej dokumentacji.
• Implementacja sandcastle jest mniej skuteczna. Na przykład. nie jest to kod <see ... copy="true" />.

Aby uzyskać więcej informacji, patrz Sandcastle's <inheritdoc> description.

Krótki opis FiXml: jest postprocesorem dokumentacji XML produkowanej przez C# \ Visual Basic .Net. Jest on zaimplementowany jako zadanie MSBuild, więc bardzo łatwo można go zintegrować z dowolnym projektem. Dotyczy on kilka irytujących spraw związanych z pisania dokumentacji XML w tych językach:

• Brak wsparcia dla dziedziczenie dokumentacji od klasy podstawowej lub interfejsu. tj. Dokumentacja dla każdego nadpisanego członka powinna być napisana od zera, chociaż zwykle całkiem pożądane jest dziedziczenie przynajmniej tej części.
• Brak wsparcia dla wstawiania często używanych szablonów dokumentacji, takich jak: „Ten typ jest Singleton. - wykorzystać swoje <see cref="Instance" /> właściwość, aby uzyskać jedyną instancję nim”, lub nawet „Inicjuje nowe wystąpienie <CurrentType> klasie.”

Aby rozwiązać wymienione kwestie, następujące dodatkowe znaczniki XML są:

• <inheritdoc />, <inherited /> tagi
• <see cref="..." copy="..." /> attrib tag w tagu <see/>.

Oto its web page i download page.