Co uważasz za dobrą dokumentację API? [zamknięte]

Właściwie dokumentacja iPhone ' a (naprawdę Mac/framework) stała się całkiem niezła. Cechy, które lubię to:

• Bardzo łatwe przejście do dokumentów z API.

• Dobrze sformatowany i fragmenty kodu chcesz skopiować i wkleić (jak podpisy metod) wyróżniają się.

• Linki do projektów z przykładowym kodem prosto od lekarzy.

• Automatyczny mechanizm odświeżania dokumentów, ale domyślnie wszystkie dokumenty są lokalne do start (aby móc żyć z flaky łącze internetowe).

• Łatwy sposób przełączania między wariantami dokumentacji (aby zobaczyć różne wersje systemu operacyjnego), a także wybrać jakie zestawy dokumentacji uruchomić / align = "left" /

• W sekcji omówienie wyjaśniono, co klasa jest dla, po której następuje sekcja łamanie metod pogrupowanych według cel (metody tworzenia i obiekt, metody zapytań o dane, metody pracy z typem konwersji, itp.), po czym następuje metoda szczegółowa wyjaśnienia.

Ja również osobiście bardzo lubiłem Javadoc i dokumentację systemu Java (używałem jej przez wiele lat), znalazłem tam korzyść, że trochę łatwiej było tworzyć własne niestandardowe dokumenty dla własnych klas, które dobrze płynęły z dokumentami systemowymi. XCode pozwala również używać Doxygen do generowania dokumentacji dla własnych klas, ale to zajmie, ale więcej pracy, aby sformatować go, jak również Docs klasy systemowej, po części dlatego, że dokumenty ramy systemu mają więcej zastosowano formatowanie.

Dobre API będzie miało następujące cechy:

• Łatwy do nauczenia
• Łatwy w użyciu, nawet bez dokumentacji
• trudne do niewłaściwego użycia
• Łatwy do odczytania i utrzymania kod, który go używa
• wystarczająco mocny, aby spełnić wymagania
• Łatwy do rozszerzenia
• odpowiednie dla publiczności

Najczęstszym błędem, jaki widzę w projektowaniu API, jest to, że deweloperzy uważają, że automatyczne generowanie komentarzy XML jest wystarczające, a następnie poprzedzają automatyczne generowanie ich API oparte na komentarzach XML. Oto o czym mówię:

///<summary>
/// Performs ObscureFunction to ObscureClass using ObscureArgument
///</summary>
void ObscureClass.ObscureFunction(ObscureArgument) { ... } 

API takie jak powyższe są tylko nieproduktywne i frustrują dewelopera korzystającego z API. Dobra dokumentacja API powinna dać programistom wskazówki, jak korzystać z API i dać im wgląd w pewne aspekty API, których w przeciwnym razie nie zauważą.

Osobiście uważam, że doskonałym przykładem dobrej dokumentacji jest dokumentacja PHP:

Na przykład: http://www.php.net/manual/en/function.fopen.php

Myślę, że skuteczna dokumentacja zawiera:

• Lista parametrów
• (przydatne) opis parametru
• Jeśli parametry są ciągiem znaków, lista wyjasnij wszystko co mozliwe możliwy parametr
• Zwraca wartości przy obu pomyślnych wykonanie i nie powiodło się wykonanie
• wszelkie wyjątki/błędy, które może podnieść
• przykłady (najważniejsze imo)

Opcjonalnie:

• Changelog
• uwagi / przykłady od innych użytkowników

Za każdym razem, gdy szukam czegoś w dokumentacji PHP, prawie wiem dokładnie, jak go używać bez konieczności przeszukiwania Internetu w celu znalezienia "lepszych" przykładów. Zwykle jedyny czas, który muszę przeszukiwać internet, to znalezienie sposobu użycia zestawu funkcji w określonym celu. W przeciwnym razie myślę, że dokumentacja PHP jest najlepszym przykładem doskonałej dokumentacji.

Co to jest think jest przykładem dobrej dokumentacji jest Python: http://docs.python.org/py3k/library/array.html

Wymienia metody, ale nie wyjaśnia dogłębnie, czym jest i jak z nich korzystać. Zwłaszcza, gdy porównasz go z dokumentami PHP.

Oto naprawdę zła dokumentacja: Databinder Dispatch . Dispatch jest biblioteką Scala dla HTTP, która abstrahuje od (Java) biblioteki HTTP Apache Commons.

Wykorzystuje wiele magii funkcjonalno-składniowej, która nie wszyscy będą bardzo jasne, ale nie dostarcza jasnego wyjaśnienia, ani decyzji projektowych za nim. Scaladocs nie są przydatne, ponieważ nie jest to tradycyjna Biblioteka w stylu Java. Aby naprawdę zrozumieć, co się dzieje, w zasadzie trzeba przeczytać kod źródłowy i trzeba przeczytać masę postów na blogu z przykładami.

Dokumentacja sprawia, że czuję się głupi i gorszy, a na pewno nie pomaga mi w tym, co muszę zrobić. Flipside to większość dokumentacji, którą widzę w społeczności Ruby-zarówno w RDoc, jak i w FAQs/websites / etc. Nie rób tylko Javadoc - musisz dostarczyć bardziej wyczerpującą dokumentację.

Odpowiedz na pytanie: "Jak zrobić X Z Y?"Możesz znać odpowiedź. I nie.

Moje główne kryteria to-powiedz mi wszystko, co muszę wiedzieć i wszystko, co kiedykolwiek będę chciał wiedzieć.

QT ma całkiem przyzwoite dokumenty: http://doc.qt.digia.com/4.5/index.html

Win32 MSDN jest również całkiem dobry, chociaż nie starzeje się dobrze.

Dokumenty Javy są dla mnie straszne. Ciągle mówią mi wszystko, czego nie chcę wiedzieć i nic z tego, co chcę wiedzieć. . NET docs ma podobną tendencję, chociaż problem polega głównie na skrajnym słowotwórstwie, nadmiar zbędnych szczegółów i cholernych stron. Dlaczego nie mogę zobaczyć zarówno podsumowania, jak i metod klasy na tej samej stronie?

Lubię dokumentację Twittera . Dla mnie dobre API jest aktualne, łatwe do odczytania i zawiera przykłady.

Myślę, że dobry dokument API musi jasno wyjaśnić:

1. Jaki problem rozwiązuje ten API
2. Kiedy należy go używać
3. Kiedy nie powinieneś go używać
4. rzeczywisty kod pokazujący "najlepsze praktyki" korzystania z API

Nie do końca Dokumentacja API, ale mimo to przydatna jest dokumentacja bazy danych Oracle, np. dla instrukcji SELECT. Podoba mi się włączenie diagramów, które pomagają wyjaśnić użycie na przykład.

Tylko kilka myśli...

1. Przykłady-Dokumentacja API win32 jest lepsza od dokumentacji iPhone ' a ze względu na:

   • (krótkie) przykłady kodu
     
     

   Głosuję na dowolny dokument API z małymi i sensownymi przykładami

2. Nigdy nie pokazuj "Form1", "asdf", "testowanie użytkowników" w zrzutach ekranu lub przykładowych kodach

   • dobre API rozwiązuje realne problemy i powinno być coś sensownego przykłady
     
     

3. Don ' t auto-gen doc

   • Dokumentacja nie powinna być wykonywana podczas pisania kodu (lub przez tego samego faceta)
   • doc jest dla nieznajomego, którego programiści zwykle nie obchodzą
     
     

4. Avoid _ _ _ v2 version of API

   • ale to nie jest problem doc

Zasadniczo opowiedz historię klasy na poziomie klasy. Dlaczego to tu jest? Co powinno zrobić? Co tu powinno być? Kto to napisał?

Opowiedz historię metod na poziomie metody. Co to robi? Bez względu na to, jak dokładne są nazwy metod, 20-30 znaków nie zawsze będzie wyciąć go dla opisowości.

@Autor:

Kto to napisał? Kto jest z tego dumny? Kto powinien wstydzić się swojej pracy?

Dokumentacja poziomu interfejsu mówi ja:

• co to powinno zrobić?
• co zwróci?

Dokumentacja poziomu implementacji mówi mi:

Jak to robi? jaki algorytm? jakie obciążenie systemu?
• jakie warunki mogą powodować problem? czy null input spowoduje problem? czy liczby ujemne są w porządku?

Dokumentacja poziomu klasy mówi mi:

Co tu się dzieje? jakich metod powinienem się spodziewać?
• co robi ta klasa reprezentować?

@ Deprecated mówi mi:

• Dlaczego jest to planowane do usunięcia?
• kiedy ma zostać usunięty?
• jaki jest sugerowany zamiennik?

Jeśli coś jest ostateczne:

Dlaczego nie chciałeś, żebym to przedłużył?

Jeśli coś jest statyczne:

Przypomnij mi na poziomie lekcyjnym, przynajmniej w domyśle.

Ogólnie: piszesz je dla następnego dewelopera, aby użyć jeśli i kiedy wygraj na loterii. Nie chcesz czuć się winny rezygnując i kupując jacht, więc zwróć trochę uwagi na jasność, i nie zakładaj, że piszesz dla siebie.

Jako korzyść poboczna, gdy ktoś poprosi Cię o pracę z tym samym kodem za dwa lata i zapomnisz o tym wszystkim, będziesz czerpał ogromne korzyści z dobrej dokumentacji w kodzie.

Pierwszym punktem dla świetnego API-dokumentacji jest dobre nazewnictwo samego API. Nazwy metod i parametrów powinny być wszystkie. Jeśli dany język jest wpisywany statycznie, użyj enum zamiast stałych String-lub int-jako parametrów, aby wybrać między ograniczonym zestawem wyborów. Jakie opcje są możliwe można teraz zobaczyć w typie parametru.

'miękka część' dokumentacji (tekst, nie kod) powinna obejmować przypadki graniczne (co się stanie, jeśli podam null jako parametr) dokumentacja klasy powinna zawierać przykład użycia.

Dobra dokumentacja powinna mieć co najmniej:

• gdy argument ma dodatkowe ograniczenia wykraczające poza jego typ, musi być w pełni określony.
• Opis stanu [wymagane] obiektu przed wywołaniem metody.
• Opis stanu obiektu po wywołaniu metody.
• Pełny opis informacji o błędach dostarczanych przez metodę(wartości zwracane, możliwe wyjątki). Po prostu nazywanie ich jest niedopuszczalne.
  • dobry przykład : rzuca ArgumentOutOfRangeException jeśli indeks jest mniejszy niż 0-lub - indeks jest większy lub równy Count.
  • zły przykład: zwraca 0 dla sukcesu lub jeden z następujących E_INVALIDARG, itd... (bez określenia, co powoduje, że argument jest nieprawidłowy). Jest to standardowe podejście "Fu developer" podjęte w PS3 SDK.

Ponadto przydatne są:

• Opis stanu obiekt, jeżeli metoda rzuca wyjątek.
• najlepsze praktyki dotyczące klas i grup klas (powiedzmy dla WYJĄTKÓW W. NET) w API.
• przykładowe użycie.

Na podstawie tego:

• przykładem Wielkiej dokumentacji jest biblioteka MSDN.
  • aby być uczciwym, wersja online tego nie cierpi z powodu trudności w nawigacji w przypadkach.
• przykładem okropnej dokumentacji jest PS3 SDK. Uczenie się API wymaga obszernego testowania argumentów metod do odgadnięcia, jakie mogą lub nie muszą być rzeczywiste wymagania i zachowanie danej metody.

Bardzo podoba mi się Dokumentacja Qt4 , najpierw konfrontuje Cię tylko z niezbędnymi informacjami, których potrzebujesz, aby wszystko działało, a jeśli chcesz kopać głębiej, ujawnia wszystkie krwawe szczegóły w podrozdziałach.

To, co naprawdę kocham, to fakt, że zbudowali całą dokumentację w Qt Creator, który zapewnia pomoc kontekstową i krótkie przykłady, kiedy ich potrzebujesz.

Jedna rzecz, którą zawsze chciałem zobaczyć w dokumentacji: paragraf "uzasadnienie" dla każdej funkcji lub klasy. Dlaczego ta funkcja tam jest? Do czego został zbudowany? Co daje, czego nie można osiągnąć w żaden inny sposób? Jeśli odpowiedź brzmi " nic " (i zaskakująco często tak jest), co to jest skrót i dlaczego ta rzecz jest wystarczająco ważna, aby mieć swoją własną funkcję?

Ten akapit powinien być łatwy do napisania-jeśli nie, to prawdopodobnie znak Wątpliwej interfejs.

IMO przykłady są najlepszą dokumentacją.

Ostatnio natknąłem się na tę dokumentację (Lift JSON ' s library), która wydaje się być dobrym przykładem tego, o co prosiło Wiele osób: ładny przegląd, dobry przykład, przypadki użycia, intencje itp.

Przejdź do strony Doxygen i spójrz na przykłady generowanego HTML. Są dobre:

Http://www.stack.nl / ~dimitri/doxygen/results.html

Lubię, aby moja dokumentacja miała krótki przegląd na górze, z w pełni opisanymi przykładami poniżej i dyskusjami pod nimi! Jestem zaskoczony, że niewiele zawiera proste argumenty funkcji z ich wymaganymi typami zmiennych i wartościami domyślnymi, szczególnie w php!

Obawiam się, że nie mogę podać przykładu, bo nie wiem, które z nich są moje ulubione, jednak Wiem, że to pewnie się nie liczy, bo jest nieoficjalne, ale Kohana 3.0 ' s Unofficial Wiki By Kerkness jest po prostu genialny! a dokumentacja Kohana 2.34 jest też dość dobrze rozplanowana, przynajmniej dla mnie. Co o tym myślicie?

Większość ludzi wymieniła punkty tworzące dobrą dokumentację API, więc nie będę ich powtarzał (specyfikacje typów danych, przykłady itp.). Podam tylko przykład, który moim zdaniem ilustruje, jak należy to zrobić:

Unity Application Block (Przejdź do sekcji Download dla CHM)

Wszystkie osoby zaangażowane w ten projekt wykonały świetną robotę dokumentując go i jak powinien być używany. Oprócz referencji API i szczegółowego opisu metody, istnieje wiele artykułów i próbek, które dają duży obraz, dlaczego i jak. Projekty z tak dobrą dokumentacją są rzadkie, przynajmniej te, z których korzystam i o których wiem.

Jedynym kryterium jakości dokumentacji jest to, że przyspiesza ona rozwój. Jeśli chcesz wiedzieć, jak coś działa, idź i przeczytaj dokumenty. Jeden doc jest lepszy od drugiego, jeśli zrozumiałeś wszystko z pierwszego doc szybciej niż z drugiego.

Wszelkie inne cechy są subiektywne. Style, odsyłacze, opisy ... znam ludzi, którzy lubią czytać książki. Doc w stylu książki (z zawartością / indeksem / etc.) będzie dla niego dobre. Inny mój przyjaciel lubi doc wszystko w środku kod. Kiedy pobiera nową bibliotekę, pobiera źródła i" czyta " je zamiast dokumentów.

Ja osobiście lubię JavaDocs. Podobnie jak Apple dev docs, z wyjątkiem części niższego poziomu, na przykład, Obj-C runtime (reference part) jest opisywany bardzo często. Kilka interfejsów API strony internetowej ma również dokumenty, które lubię.

Nie lubię MSDN (ogólnie jest dobry, ale jest zbyt wiele wariantów tego samego dokumentu, często się gubię).

Dokumentacja jest tylko częścią projektu API. I można by argumentować, że to drugie jest o wiele ważniejsze niż tylko nazewnictwo. Pomyśl o wymownych nazwach metod nie powielających się itp.

Zdecydowanie polecam obejrzenie prezentacji Josha Blocha na ten temat: http://www.infoq.com/presentations/effective-api-design lub http://www.youtube.com/watch?v=aAb7hSCtvGw

To obejmuje nie tylko to, czego szukasz, ale znacznie więcej.

Wiele praktycznych, rzeczywistych przykładów jest koniecznością. Niedawne przepisanie dokumentacji API jQuery jest dobrym przykładem, podobnie jak legendarne dokumenty Django.

Najlepszą dokumentacją jaką znalazłem jest Python . Możesz użyć sphinx do generowania dokumentacji źródłowej do HTML, LaTeX i innych, a także generować dokumenty z plików źródłowych; dokumentu API, którego szukasz.

API docs to nie tylko jakość ostatecznej dokumentacji, ale także to, jak łatwo jest programistom i / lub pisarzom technicznym ją napisać, więc wybierz narzędzie, które ułatwi pracę.

Większość rzeczy związanych z dobrą dokumentacją została już wspomniana, ale myślę, że jest jeden aspekt w dokumentacji API JavaDoc, którego brakuje: ułatwienie rozróżniania scenariuszy użycia wszystkich różnych klas i interfejsów, szczególnie rozróżnianie klas, które powinny być używane przez klienta biblioteki, a tych, które nie powinny.

Często JavaDoc jest prawie wszystkim, co dostajesz i zazwyczaj nie ma strony dokumentacji pakietu. Jeden jest wtedy konfrontacja z listą setek lub nawet więcej klas: od czego i jak zacząć? Jakie są typowe sposoby korzystania z biblioteki?

Byłoby dobrze, gdyby istniały konwencje, jak ułatwić dostarczanie tych informacji w ramach JavaDoc. Następnie wygenerowana Dokumentacja API może pozwolić na różne widoki dla różnych grup ludzi - co najmniej dwóch grup: tych, którzy implementują bibliotekę i tych, którzy jej używają.

Uważam Google API za piękny przykład dobrego API dokumentacji.

Mają:

1. widok z lotu ptaka całej struktury APIs
2. przegląd głównych funkcji pojedynczego API
3. ładne i kolorowe przykłady na szybką opinię
4. szczegółowe referencje
5. blog na bieżąco aktualizowany
6. a google groups które dokumentują problemy i rozwiązania
7. Filmy
8. FAQ
9. Artykuły
10. prezentacje
11. Code
12. wyszukiwarka, aby wczołgać się w stos dokumentacji

To jest to! Kiedy gram na stronie dokumentacji Google API, czuję się jak w domu.