Czyszczenie PyXMPP

Opublikowane przez jajcus

Najwyraźniej jest jakieś zainteresowanie moją pythonową biblioteką
XMPP. Ludzie (przynajmniej paru) chcą tego używać, ale wielu od razu się
zniechęca brakiem dokumentacji, inni po próbach zrozumienia o co w tym biega.
Nie dziwię się — kod zamotany jak rzadko, a dokumentacji praktycznie brak.
Bardziej dziwię się ludziom takim jak pete, czy Zgoda, którzy tego używają i nawet mnie
z tego powodu nie męczą. Jednak uznałem, że trzeba coś z tym zrobić…

Więc od paru dni zamiast dodawać nowe ficzery do CJC, poprawiać
w nim bugi, czy implementacje protokołów w PyXMPP to ślęczę nad kodem PyXMPP
i, terroryzowany przez pylinta czyszczę kod,
co jakiś czas robiąc: cvs commit -m "cleaning up...". Przy jakiś
czas coś psuję głupimi literówkami, albo zamierzonymi zmianami w API PyXMPP
(sorry developerzy), np. zamiana nazwy parametru konstruktora klasy Stanza
z type na typ, bo ta pierwsza nazwa zakrywała nazwę wbudowanej
funkcji. Jak już wspominałem większość marudzenia pylinta dotyczy braku
docstringów, a więc je dodawałem na bieżąco. Oczywiście nie
"", ale w miarę konkretną dokumentację, która się może jakiemuś
developerowi przydać. I tu wkracza Epydoc…

Normalnie do przetwarzania dokumentacji w pythonie służy narzędzie
pydoc. Jednak jest ono głupie, bo traktuje docstringi jako
czysty tekst, bez formatowania czy hyperlinków. Taka dokumentacja jest mało
czytelna i niewygodna. Już jakiś czas temu szukałem informacji na temat
robienia porządnej dokumentacji do kodu Pythona i dowiedziałem się, że the
right way to jest (lub raczej będzie) używanie w docstringsch reStructuredText.
Narzędzi do przetwarzania tego wtedy nie znalazłem (słabo szukałem, albo
jeszcze nie było), znalazłem tylko docutils które, między innymi,
takim narzędziem mają się stać, ale na razie umieją tylko parsować
reStructuredText i konwertować to do mądrzejszych formatów.
Mimo braku narzędzia do obróbki tego jednak już wtedy postanowiłem
reStructuredText używać. I nawet użyłem w tych skrawkach
dokumentacji które zdążyłem zrobić.

Teraz przy czyszczeniu kodu znowu szukałem narzędzia do generowania
dokumentacji z kodu. Tym razem znalazłem. Docutils wciąż nie
umieją wyciągać dokumentacji z kodu Pythona, ale mogą być wykorzystane
przez Epydoca, który to potrafi.
Ma on niby swój markup dla docstringów, ale potrafi, przy pomocy
docutils obsłużyć także reStructuredText (ale tylko tworząc
dokumentację w HTML). Więc to właśnie podpiąłem pod doc/Makefile.
Okazało się, że stare kawałki dokumentacji musiałem popoprawiać, żeby
Epydoc sobie z tym poradził. Nowe tworzyłem od razu pod
tandem Epydoc+docutils. I nawet są jakieś
efekty. Otrzymana dokumentacja wygląda nieźle, jest dość przejrzysta… tylko
ma olbrzymie braki. :-( Kiedy ja to wszystko opiszę?

18 uwag do wpisu “Czyszczenie PyXMPP”

  2. Nie obrażę się 🙂
    Mam nadzieję, że nie chodzi o ortografię… 😉 właśnie się zorientowałem, że przed wysłaniem zapomniałem sprawdzić (\ss w moim VIMie), a teraz będzie to trudniejsze…

    Polubienie

    Odpowiedz

  4. Hmm, a kiedy nowy relase, bo cały czas widnieje 0.5, a z twojego sprawozdania wynika, że CVS, czy czego tam używasz, jest mało stabilny (czytaj, możliwość występowania błędów typologicznych etc.).

    Polubienie

    Odpowiedz

  5. axquan:
    Jak to w OS: trudno powiedzieć. Możliwe, że za dwa tygodnie ogłoszę znowu "bug hunting weekend" i jak nie będzie poważnych błędów to zrobię nowe wydanie, chyba że wcześniej nie oprę się pokusie dodawania nowych ficzerów, albo zajęcia się zupełnie czymś innym.

    Polubienie

    Odpowiedz

  6. pete: doxygen powstało dla C++ i wsparcie dla pythone nie jest takie jak być powinno (kumpel się tym bawił, ja chyba kiedyś też). Epydoc powstało właśnie dla pythona i dobrze sobie radzi z jego specyfiką (chociażby słabe typowanie). Poza tym umie reStructuredText który, według ludzi od Pythona jest tym właściwym formatem.

    Polubienie

    Odpowiedz

  8. zgoda: ale to używa komentarzy… błe. Nie bez powodu w pythonie są docstringi. Używając docstringów nie muszę szukać dokumentacji — wystarczy że zrobię "pydoc moduł.funkcja". Cicho liczę na to, że kiedyć pydoc będzie umiał reStructuredText… to byłoby super.
    A jak zaczynałeś od Javy, to tylko wspomną, że Epydoc oprócz swojego markupu oraz reStructuredText obsługuje też tagi JavaDoc (ale w docstringach, nie w komentarzach).

    Polubienie

    Odpowiedz

  11. To jest "keyword parameter" używany wraz z nazwą klasy. Trudno o pomyłkę, a IMHO mniej czytelny będzie kod:
    Message(stanza_to="zgoda@chrome.pl",stanza_from="jajcus@jabber.bnet.pl",stanza_type="chat",stanza_id="msg1",subject="To be verbose or not to be verbose")
    niż:
    Message(to="zgoda@chrome.pl",fr="jajcus@jabber.bnet.pl",typ="chat",sid="msg1",subject="To be verbose or not to be verbose")
    Chociaż jak to napisałem to już sam nie wiem. Po prostu słowo kluczowe "from" i builting "type" (tego drugiego spokojnie mogłoby nie być) brużdżą 😦
    A zmiana nazw wszystkich parametrów, to byłoby chyba zbyt drastyczne psucie API… a może nie?
    Developerzy! Jak byście chcieli żeby to było?

    Polubienie

    Odpowiedz

  13. Jajcuś: może przedrostek ,s' do wszystkiego? sfrom, stype itd.
    ,,typ'' mi się osobiście mocno nie podoba. (ale ja właściwie nie jestem nawet userem, więc to tylko taka luźna sugestia)

    Polubienie

    Odpowiedz

  17. Pete: to może jeszcze notacja węgierska nazw funkcji? nie! to ma być proste. propozycja Jarka chyba najbardziej mi się podoba, chociaż nie lubię "szerokich" programów (dlatego też nie stawiam spacji po przecinku itp.)
    Mam jeszcze jeden pomysł z mieszanymi prefiksami: to_jid, from_jid,stanza_type,stanza_id

    Polubienie

    Odpowiedz

Co o tym sądzisz?