Ogłoszenie ujednoliconego środowiska dokumentacji programu .NET w witrynie docs.microsoft.com

Autorem tego postu jest Jeff Sandquist, dyrektor naczelny zespołu ds. rozwoju i ekosystemu platformy Azure.

Prawie rok temu pilotowaliśmy dokumentację referencyjną platformy .NET Core dotyczącą docs.microsoft.com. Dzisiaj z przyjemnością ogłaszamy nasze ujednolicone środowisko referencyjne interfejsu API platformy .NET. Rozumiemy, że produktywność deweloperów jest kluczowa — od dewelopera hobbystycznego, po startup po przedsiębiorstwo. Mając to na uwadze, ściśle współpracujemy z zespołem platformy Xamarin, aby ustandaryzować sposób dokumentowania, odnajdywania i nawigowania po interfejsach API platformy .NET w firmie Microsoft.

Cała dokumentacja platformy .NET — w jednym miejscu

Wcześniej, jeśli chcesz znaleźć element . Zestaw SDK oparty na platformie NET dostarczony przez firmę Microsoft musiał poświęcić trochę czasu na ulubioną wyszukiwarkę, próbując znaleźć miejsce, w którym można go pobrać, a także odnaleźć odpowiednią dokumentację interfejsu API.

W przyszłości planujemy mieć wszystkie elementy . Zestawy SDK zgodne z platformą NET są ujednolicone i można wyszukiwać w jednym miejscu: https://docs.microsoft.com/dotnet/api. W tym miejscu znajdziesz dokumentację referencyjną dla programów .NET Framework, .NET Core, .NET Standard i Xamarin, a także dokumentację dla naszych pakietów NuGet platformy Azure. W nadchodzących miesiącach dodamy więcej zestawów SDK do tego środowiska.

Wprowadzenie do przeglądarki interfejsu API

Naszym głównym celem jest wprowadzenie środowiska przypominającego funkcję IntelliSense w celu wyszukiwania wszystkich interfejsów API platformy .NET z przeglądarki internetowej. Możesz wyszukać przestrzeń nazw, klasę, metodę lub interfejs, wpisując jego pełną lub częściową nazwę bezpośrednio na stronie przeglądarki interfejsu API.

API Browser

Jeśli nie masz pewności, do którego zestawu SDK należy określony typ, element członkowski lub przestrzeń nazw, możesz po prostu wybrać pozycję Wszystkie interfejsy API na liście rozwijanej Zakres interfejsu API i wyszukać wszystkie dostępne dokumenty referencyjne. Alternatywnie, jeśli chcesz ograniczyć wyszukiwanie, możesz wybrać określoną strukturę lub zestaw SDK, a także jego wersję — powiedzmy , .NET Framework 4.7 i wyszukać tylko w tym zestawie interfejsów API.

Środowisko przeglądarki interfejsu API jest również zintegrowane w górnej części spisu treści dla programu . Interfejsy API oparte na platformie NET, które umożliwiają szybkie znajdowanie dowolnego interfejsu API niezależnie od tego, gdzie znajdujesz się w dokumentacji referencyjnej:

API Browser in-page

Po utworzeniu określonej przestrzeni nazw przeglądarka interfejsu API jest ograniczona tylko do rodziny połączonych ze sobą interfejsów API, więc wyszukiwanie zawsze zwraca najlepsze możliwe wyniki na podstawie kontekstu.

Obsługa wersji

Nie musisz już zastanawiać się, czy typ ma elementy członkowskie dostępne w określonej wersji programu .NET Framework lub pakietu NuGet usługi Azure Storage — wystarczy zmienić wersję kontrolki przeglądarki interfejsu API, a zawartość będzie odpowiednio dostosowywana:

Reference TOC

Kompilowane z myślą o środowisku Open Source

Aby utworzyć przeglądarkę interfejsu API, użyliśmy otwartych standardów i narzędzi. U podstaw korzystaliśmy z narzędzia docFX — otwartego łańcucha narzędzi generowania dokumentacji wraz z aplikacją mdoc platformy Xamarin.

Cała zarządzana dokumentacja referencyjna jest teraz automatycznie generowana na podstawie plików binarnych, które są dostarczane w programie NuGet lub są częścią głównych dystrybucji platform, takich jak .NET Framework lub .NET Core.

Nasza infrastruktura ciągłej integracji umożliwia nam dokładną dokumentację najnowszych interfejsów API, które mogą być teraz publiczne w ciągu kilku godzin od wydania, otwarte dla współtworzenia. Ustandaryzowaliśmy również całą dokumentację interfejsu API platformy .NET w formacie ECMAXML, która tworzy spójną i kompleksową reprezentację interfejsu API niezależnie od udokumentowanego zestawu SDK. Ponadto nie musisz znać zawiłości formatu pliku, ponieważ możesz współtworzyć zawartość w języku Markdown osadzoną w automatycznie generowanych dokumentach. Wkład społeczności do dokumentacji referencyjnej zostanie włączony w ciągu następnego miesiąca.

Koncentracja na zawartości

Oprócz nowych środowisk zoptymalizowaliśmy również zawartość referencyjną, aby być bardziej czytelna i czytelna. Zaktualizowaliśmy spis treści tak, aby zawsze był skoncentrowany na przestrzeni nazw. Niezależnie od tego, czy przeglądasz informacje o przestrzeni nazw, typie czy elemencie członkowskim, zawsze wyświetlamy tylko nadrzędną przestrzeń nazw ze wszystkimi typami & podrzędnymi odpowiednich grupowanych elementów członkowskich:

Reference TOC

Oznacza to, że strony referencyjne są odsuwane i najpierw pokazują najważniejsze informacje, takie jak ogólne omówienie i przykłady — wszystkie na pierwszy rzut oka.

Zobaczysz również przykłady, które są istotne dla Ciebie bezpośrednio od początku, odfiltrowane do wybranego języka programowania — nie trzeba już przewijać do dołu strony, aby je znaleźć.

Opinie oparte na opiniach

To dopiero początek przebudowy środowiska dokumentacji referencyjnej. Chcemy usłyszeć twoją opinię na temat sposobu, w jaki możemy uczynić naszą dokumentację bardziej atrakcyjną, przydatną i jak najszybszą. Przejdź do naszej witryny UserVoice i poinformuj nas, jak możemy ulepszyć środowisko przeglądarki interfejsu API. Możesz również zawsze skontaktować się z nami na Twitterze, @docsmsft, aby uzyskać szybkie aktualizacje.