Najlepszy sposób dodawania dokumentacji dewelopera do projektów Visual Studio

Question

Zasadniczo pytanie brzmi: Gdzie (iw jakim formacie) powinienem przechowywać tekstową dokumentację dla programistów związaną z moimi projektami Visual Studio?

Aby opracować: komentarze XML są świetne, ale nie obejmują wszystkich przypadków użycia. Czasami chcesz opisać architekturę klasową projektu na wysokim poziomie, dodać notatki o użytkowaniu do swojej biblioteki lub po prostu zostawić wiadomość innego rodzaju dla przyszłych pokoleń programistów pracujących nad tym projektem.

Chciałbym dodać te dokumenty bezpośrednio jako pliki do projektu Visual Studio, aby zapewnić (a), że są one dostępne dla programisty bez dalszego wyszukiwania i (b) są kontrolowane w wersji (przy użyciu tego samego svn/git/jakiekolwiek repozytorium jako kod źródłowy).

Obecnie dodajemy do projektu folder _Documentation i używam plików tekstowych, ale nie jestem pewien, czy jest to najlepsze rozwiązanie. Visual Studio nie ma opcji automatycznego zawijania tekstu na tekst i ręcznego ustawiania podziałów linii po każdej zmianie jest denerwujące. Z drugiej strony, dokumenty programu Word nie działają dobrze z kontrolą wersji, a TeX jest zbyt trudny do skonfigurowania i nauczenia na każdym komputerze programisty.

Czy istnieje sprawdzona najlepsza praktyka w tym zakresie?

---

wiem, że tam Edycja/Advanced/Word Wrap, ale to tylko wpływa na wyświetlacz, a nie sam plik.

Answer 1

Po prostu miałem ten sam problem - tylko zauważyłem, że udało mi się dodać plik HTML. Po otwarciu przełącz się na "Design" u dołu ekranu. Możesz zmienić Konstruowanie Akcja od „Content” do „None”

Ponieważ jest to zakodowany dokument HTML, możliwe jest również użycie wbudowanych zdjęcia (np schemat)

także dla mojego celu (przewodnik programowania, opis architektury, przykłady użycia bazy danych) Zdecydowałem się utworzyć oddzielny projekt (_Documentation) jako Windows Forms, ponieważ pozwoli to na to (lub nowemu programistowi) na uruchomiony przykład.

Answer 2

używam GhostDoc (visual studio dodatek) dla dokumentacji mojego projektu jako dodam klas, metody, właściwości itp: http://visualstudiogallery.msdn.microsoft.com/46A20578-F0D5-4B1E-B55D-F001A6345748

Answer 3

Masz możliwość, w komentarzach XML, aby zawierać wiele danych, które następnie można pobrać za pomocą narzędzia takiego jak Sandcastle (site) i przekształcić w rzeczywistą witrynę referencyjną w stylu MSDN.

Używam tej metody i piszę długie komentarze XML (MSDN comment tags) (w razie potrzeby), używając <para></para> do generowania akapitów i wyjaśniania wszelkich wzorców, przyczyn biznesowych lub informacji architektonicznych niezbędnych dla przyszłych modyfikatorów/programistów. Używam go również do podania przykładów użycia.

Dobra partia testów (dobrze napisana i nazwana) może również oświetlić cel kodu, działając jako specyfikacja.

Mam nadzieję, że może być trochę informacyjny w badaniach :)

Answer 4

Komentarze XML jest najlepsze dla dokumentowanie konkretnej metody i nie nadaje się do pisania długiej koncepcyjny treści. Długie komentarze XML mogą negatywnie wpłynąć na czytelność kodu.

Podobała mi się funkcja dokumentowania tematów koncepcyjnych Sandcastle, możemy tworzyć i przechowywać dokumentację koncepcyjną, zarówno związaną z funkcjonalnością, jak i architekturą, oraz scalać ją z dokumentacją Code (komentarze XML). Znaczniki, których można używać do pisania tematów konceptualnych, można rozszerzyć, co oznacza, że ​​możemy nawet stosować szablony korporacyjne.