Jak udokumentować eksperymentalne lub niekompletne interfejsy API, takie jak @deprecated?

12

Czy istnieje dobry termin, który jest podobny, ale różni się od „przestarzałe”, co oznacza, że ​​metoda lub interfejs API znajduje się w bazie kodu, ale nie należy go stosować, ponieważ jego implementacja nie jest kompletna lub prawdopodobnie ulegnie zmianie? (Tak, wiem, te metody nie powinny być publiczne, yada yada yada. Nie stworzyłem swojej sytuacji, po prostu staram się jak najlepiej wykorzystać.)

Co ludzie sugerują? Eksperymentalny, Nieukończony, coś jeszcze?

Jeśli tworzę dokumentację javadoc dla tego API, która wciąż się zmienia, czy powinienem używać tagu @deprecated, czy jest lepsza konwencja? Dla mnie @deprecated oznacza, że ​​ten interfejs API jest stary i dostępny jest nowszy preferowany mechanizm. W mojej sytuacji nie ma alternatywy, ale niektóre metody interfejsu API nie są gotowe i dlatego nie należy ich używać. W tym momencie nie mogę uczynić ich prywatnymi, ale chciałbym umieścić wyraźne ostrzeżenia w dokumentacji.

documentation terminology api documentation-generation javadocs Michael Levy
źródło
Przydałby się również tag „niestabilny”. Znaczenie byłoby inne. „To powinno działać OK, ale możemy wprowadzić pewne zmiany w przyszłości”.
Borjab,

Odpowiedzi:

8

Odpowiednim terminem jest najprawdopodobniej inkubator , ten jest używany przez Google i Apache:

  • google-web-tool-kit-incubator

    Oficjalny inkubator widżetów i bibliotek dla Google Web Toolkit ...

  • Inkubator Apache

    ... brama do projektów open source, które mają stać się pełnoprawnymi projektami Apache Software Foundation ...

Jeśli przyjrzysz się bliżej projektom, o których mowa powyżej, możesz zauważyć, że „eksperymentalne” interfejsy API (np. W GWT) zwykle mają „dedykowane” nazwy pakietów, takie jak com.google.gwt.gen2. Ma to na celu uniknięcie zanieczyszczenia przyszłego „sfinalizowanego” interfejsu API przeznaczonego do stałego publicznego spożycia - ponieważ, wiesz,

„Publiczne interfejsy API, takie jak diamenty, są wieczne. Masz jedną szansę, aby zrobić to dobrze, więc daj z siebie wszystko ...” (Joshua Bloch, Jak zaprojektować dobry interfejs API i dlaczego to ma znaczenie )

komar
źródło
2
Byłem skłonny do „Eksperymentalnego” po obejrzeniu API takich jak developer.chrome.com/extensions/experimental.html
Michael Levy
10

Korzystałbym @deprecatedz czysto praktycznych powodów.

Chociaż @deprecatednie przekazuje dokładnego znaczenia, jakie chciałbyś, ma on znaczącą zaletę: kompilator Java ma wbudowaną obsługę. Kompilacja z -deprecationflagą pozwala znaleźć wszystkie miejsca, w których zastąpisz przestarzałą metodę, pomagając użytkownikom bardzo szybko znaleźć podejrzany kod. Możesz użyć @deprecatedtagu Javadoc, aby wyjaśnić, co tak naprawdę dzieje się każdemu, kto chce przeczytać twoją dokumentację. W tym miejscu możesz powiedzieć użytkownikowi, że interfejs API jest eksperymentalny, powinien być używany na własne ryzyko i tak dalej.

dasblinkenlight
źródło
1
+1. Doskonały punkt Posiadanie wbudowanego wsparcia jest niezbędne dla takich części interfejsu API i zachęca użytkowników do zapoznania się z dokumentacją, aby zrozumieć, dlaczego te części są oznaczone jako nieaktualne.
Arseni Mourzenko
2
Byłem skłonny do czegoś w rodzaju „* @deprecated To jest eksperymentalny interfejs API i prawdopodobnie się zmieni” co najmniej, aby uzyskać IDE i dokumenty w celu wyróżnienia metody, a następnie uzyskać krótkie wyjaśnienie.
Michael Levy,
Pamiętaj tylko, że przestarzałe utworzy wiele ostrzeżeń. To może nie być tak złe, jak się wydaje. Ostrzeganie o funkcjach eksperymentalnych może być OK.
Borjab,
3

Nigdy nie widziałem czegoś takiego w innych interfejsach API, ponieważ funkcje eksperymentalne lub niekompletne nie mają nic wspólnego z publicznym interfejsem API.

Ponieważ nie masz wyboru, po prostu umieść wyraźnie widoczne ostrzeżenie, że część interfejsu API może ulec zmianie.

Arseni Mourzenko
źródło
Dobrze. Na przykład: junit.org/apidocs/org/junit/experimental/package-summary.html Nawiasem mówiąc, używanie pakietu było okropnym pomysłem. Gdy interfejs API będzie niestabilny, musisz zmienić pakiet, aby złamać wszystkie zależności. Adnotacja java byłaby znacznie lepsza
Borjab,