17.11. Tworzenie dokumentacji aplikacji
Problem
Chcemy stworzyć dokumentację interfejsu API dla naszej aplikacji. Najlepiej by było, gdyby cała dokumentacja była zapisana w tych samych plikach co kod źródłowy.
Rozwiązanie
Dobrą praktyką programistyczną jest poprzedzanie metod, klas i modułów komentarzami, które pozwalają czytelnikom zorientować się, czego dotyczą określone konstrukcje. W języku Ruby wprowadzono dodatkowe udogodnienie polegające na możliwości łatwego przekształcenia tych komentarzy na zbiór stron HTML, które składają się na dokumentację kodu. Jest to mechanizm podobny do JavaDoc dla języka Java, PyDoc dla Pythona i Pod dla Perla.
Oto prosty przykład. Załóżmy, że aplikacja zawiera tylko jeden plik — sum.rb, w którym ...
Get Ruby. Receptury now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.
