Как поддерживать примеры кода в Javadocs в актуальном состоянии

Я работаю над небольшой библиотекой, которая обеспечивает реализацию основных, хорошо известных строковых метрик. Главным образом для моего собственного образования. Так что развитие происходит всякий раз, когда у меня есть немного свободного времени.

Из-за этого я автоматизировал большинство процессов, поэтому могу выпускать версию так же часто, как и над ней, без особых усилий. Однако поддержка документа Java все еще является бременем, поскольку включает примеры.

По мере развития API мне приходится проверять каждый пример снова и снова. Есть лучший способ сделать это?

Я подумал о том, чтобы перенести документацию и примеры в отдельный проект (например, в Caliper Tutorial ), чтобы его можно было повторно проанализировать и скомпилировать вместе с обычным кодом. Однако это отодвигает документацию от класса, о котором идет речь.

Так что да. Я хотел бы иметь свой торт и есть его тоже. : D

 * <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>

Если выше это слишком абстрактно. Это образец документации. В настоящее время я добавляю статические конструкторы в соответствии с рекомендациями Effective Java, например, Tokenizers.createQGram(2)при устаревании метода конструктора. Каждый раз, когда я делаю что-то подобное, мне приходится обновлять приведенный выше пример кода и проверять, работает ли он по-прежнему.

Это может не ответить на ваш вопрос - в зависимости от того, насколько «необходимо» иметь эти примеры в вашей документации.

Возможно, вы могли бы использовать другой подход: приведите примеры в своих тестах JUnit. (Возможно, даже такой пакет, как com.examples). Проблема с кодом в комментариях заключается в том, что ваша IDE по большей части будет игнорировать его. Но ваша IDE проверит код в ваших тестах JUnit. Делая это, вы гарантируете, что примеры кода являются «правильными» - тесты либо не скомпилируются, либо просто не пройдут, если вы не обновили их.

Я не волшебник с Javadocs, но может быть способ связать документацию вашего исходного файла с файлом JUnit с примером кода в нем. Я действительно не знаю, с чего начать. Беглый поиск в Google показал мне @seeтег . Я протестировал его в проекте, но не тестировал его в реальном Javadoc после того, как он был сгенерирован.

Это определенно потребует предварительных исследований, но я действительно думаю, что в конечном итоге вам было бы лучше, если бы примеры кода на самом деле компилировались.

В качестве дополнительной цели вы также можете добавить покрытие кода при запуске примеров JUnit. Таким образом, вы сразу узнаете, какая часть вашей кодовой базы покрыта вашими примерами.