Odniesienie do lepszego samopoczucia?

Question

To, co naprawdę mnie nie kręci, to ich dokumentacja. Potrzebuję dobrego odniesienia i zamiast wyjaśniać, co jest dla mnie dobrym referencją, podam przykład:

java.sun.com/javase/6/docs/api/ Tak, kocham to. Jest to również: cppreference.com/wiki/stl/vector/start

Z drugiej strony, co uważam o Boost jest coś takiego: http://www.boost.org/doc/libs/1_40_0/libs/smart_ptr/shared_ptr.htm

Zasadniczo niektóre długo strona tekstu. Prawie bez formatowania, trochę pogrubionego tekstu tu i tam i mam nadzieję, że niektóre połączenia między elementami. Nie wspominając o tym, że smart_ptr jest jedną z lepiej udokumentowanych bibliotek.

Jeśli nie znajdziesz różnicy między powyższymi i powyższymi przykładami, przestań czytać i zignoruj ​​ten post. Nie zrozum mnie źle, piszę C++ i używam Boost. W mojej firmie używamy co najmniej 4 ich bibliotek, wciąż za każdym razem, gdy muszę sprawdzać prototyp metody, na przykład wyciąga mnie to z nerwów przeglądając ich eseje. I tak, wiem, że Boost to projekt oparty na współpracy i że różne biblioteki są opracowywane przez różne zespoły.

Czy ktokolwiek z was podziela moje rozczarowanie odniesieniem do Boost i czy znasz jakąś lepszą stronę dokumentującą biblioteki Boost?

Answer 1

Ogólnie rzecz biorąc, nie uważam, że dokumentacja jest , że złe. Zasadniczo informacja jest tam "gdzieś". Głównym problemem, jaki widzę, jest brak jednolitości, co utrudnia znalezienie "gdzieś". Kiedy piszesz w swoim pytaniu, dokumenty zostały napisane przez różnych ludzi i przez inne czasy, i to prawdopodobnie jest przyczyną tego braku wspólnej struktury.

Z linków java i cppreference cytowanych w przykładzie wynika, że ​​jesteś bardziej zainteresowany streszczeniem interfejsu niż w "samouczku" lub "motywacji". W przypadku shared_ptr, czy http://www.boost.org/doc/libs/1_40_0/libs/smart_ptr/shared_ptr.htm#Synopsis zapewnia to, czego szukasz?

Dla niektórych bibliotek przydatne są katalogi "test" i "przykład" pod numerem libs/<library_name>.

Możesz publikować swoje pytania, komentarze i sugestie na listach dyskusyjnych pod numerem users i/lub documentation. Z tego, co widzę, specjalni opiekunowie bibliotek z zadowoleniem przyjmują konkretne propozycje ulepszenia dokumentacji.

Answer 2

Jeśli szukasz tekstu wprowadzającego, znalazłem książkę Bjorn Karlsson bardzo dobrze. To było chwilę temu, kiedy przeczytałem, więc teraz mogą być dostępne bardziej aktualne teksty. Find it here.

Answer 3

Patrząc na link języka Java, a ponad połowa z nich jest nieaktualny od dłuższego już czasu :)

Masz narzędzi formacie PDF i PDF docs teraz .. Istnieją narzędzia, a bardziej na jego sposób, od boostbooka dla autorów piosenek wieków temu, do podsumowania i więcej .. Twórz własne lub parsuj większość kosztu marży już przesadzonego projektu :)

Answer 4

Zdecydowanie się zgadzam. Javadoc to paskudne, paskudne rzeczy. Jest jednak dokładny i spójny w prawie każdym projekcie. Porównaj przeglądanie losowej dokumentacji projektu Jakarta z dokumentacją losowego projektu Boost.