Jak aktualizować przykłady kodu w javadocs

Pracuję nad małą biblioteką, która zapewnia implementacje podstawowych, dobrze znanych metryk ciągu. Głównie dla mojej własnej edukacji. Rozwój odbywa się za każdym razem, gdy mam trochę wolnego czasu.

Z tego powodu zautomatyzowałem większość procesów, dzięki czemu mogę wypuszczać wersję tak często, jak pracuję nad nią bez większego wysiłku. Jednak utrzymanie dokumentu Java jest nadal dużym obciążeniem, ponieważ zawiera przykłady.

Gdy API ewoluuje, muszę ręcznie sprawdzać każdy przykład w kółko. Czy jest na to lepszy sposób?

Zastanawiałem się nad przeniesieniem dokumentacji i przykładów do osobnego projektu (np. Samouczek Calipera ), aby można je było ponownie przefakturować i skompilować wraz ze zwykłym kodem. To jednak odsuwa dokumentację od klasy, której dotyczy.

Więc tak. Chciałbym mieć ciasto i też je zjeść. :RE

 * <h2>Tokenization</h2>
 * 
 * Tokenization cuts up a string into tokens e.g.
 * <code>chilperic ii son of childeric ii</code> is tokenized into
 * <code>[chilperic, ii, son, of,
 * childeric, ii]</code>. Tokenization can also be done repeatedly by tokenizing
 * the individual tokens e.g.
 * <code>[ch,hi,il,il,lp,pe,er,ri,ic, ii, so,on, of, ch,hi,il,ld,de,er,ri,ic, ii]</code>
 * <p>
 * 
 * <pre>
 * <code>
 * {@code
 *  return new StringMetricBuilder()
 *          .with(new SimonWhite<String>())
 *          .tokenize(new Whitespace())
 *          .tokenize(new QGram(2))
 *          .build();
 * }
 * </code>
 * </pre>
 * 
 * <p>

Jeśli powyższe to zbyt abstrakcyjne. To jest próbka dokumentacji. Obecnie dodaję konstruktory statyczne zgodnie z zaleceniami Effective Java, np. Tokenizers.createQGram(2)Podczas amortyzacji metody konstruktora. Za każdym razem, gdy robię coś takiego, musiałbym zaktualizować powyższy przykładowy kod i sprawdzić, czy nadal działa.

To może nie odpowiedzieć na twoje pytanie - w zależności od tego, ile „wymagań” ma mieć te przykłady w dokumentacji.

Być może możesz zrobić z innej perspektywy: podaj przykłady w testach JUnit. (Być może nawet pakiet taki jak com.examples) Problem z kodem w komentarzach polega na tym, że twoje IDE w większości go zignoruje. Ale twoje IDE zweryfikuje kod w testach JUnit. Robiąc to, upewniasz się, że przykłady kodu są „poprawne” - testy albo się nie skompilują, albo po prostu zakończą się niepowodzeniem, jeśli ich nie zaktualizujesz.

Nie jestem czarodziejem z Javadocs, ale może istnieć sposób na połączenie dokumentacji pliku źródłowego z plikiem JUnit z przykładowym kodem. Ale naprawdę nie wiedziałbym od czego zacząć. Pobieżne googling pokazał mi @seetag . Przetestowałem to w projekcie, ale po wygenerowaniu nie przetestowałem go w javadoc.

To z pewnością wymagałoby trochę badań z góry, ale naprawdę myślę, że lepiej byłoby na dłuższą metę, gdyby twoje przykłady kodu były właśnie kompilowane.

Jako cel rozciągnięty możesz również dodać pokrycie kodu podczas uruchamiania przykładów JUnit. W ten sposób będziesz na pierwszy rzut oka wiedzieć, ile twojej bazy kodu obejmuje twoje przykłady.