Как документировать экспериментальные или неполные API, такие как @deprecated?

12

Есть ли хороший термин, который похож, но отличается от «не рекомендуется», чтобы означать, что метод или API находятся в базе кода, но не должны использоваться, потому что их реализация не завершена или, вероятно, изменится? (Да, я знаю, эти методы не должны быть общедоступными, яда, яда, яда. Я не создавал свою ситуацию, я просто пытался извлечь из этого максимум пользы).

Что люди предлагают? Экспериментальный, неполный, что-то еще?

Если я создаю документацию по Javadoc для этого API, которая все еще находится в процессе разработки, должен ли я использовать тег @deprecated или есть лучшее соглашение? Для меня @deprecated подразумевает, что этот API старый и доступен более новый предпочтительный механизм. В моей ситуации альтернативы нет, но некоторые методы в API не завершены и поэтому не должны использоваться. На данный момент я не могу сделать их конфиденциальными, но я хотел бы поместить четкие предупреждения в документы.

Майкл Леви
источник
Тег «Нестабильный» также будет полезен. Значение будет чем-то другим. «Это должно работать нормально, но мы можем внести некоторые изменения в будущем».
Борхаб,

Ответы:

8

Подходящий термин, скорее всего, инкубатор , этот термин используют Google и Apache:

  • Google-веб-инструментарий-инкубатор

    Официальный инкубатор виджетов и библиотек для Google Web Toolkit ...

  • Apache Incubator

    ... шлюз для проектов с открытым исходным кодом, предназначенных стать полноценными проектами Apache Software Foundation ...

Если вы внимательно посмотрите на проекты, упомянутые выше, вы можете заметить, что «экспериментальные» API (например, в GWT), как правило, имеют «выделенные» имена пакетов, например com.google.gwt.gen2. Это сделано для того, чтобы не загрязнять будущий «доработанный» API, предназначенный для постоянного общественного потребления, - потому что

«Публичные API, как бриллианты, вечны. У вас есть один шанс сделать это правильно, поэтому старайтесь изо всех сил ...» (Джошуа Блох, « Как создать хороший API и почему это важно» )

комар
источник
2
Я склонялся к «Экспериментальному», увидев такие API-интерфейсы, как developer.chrome.com/extensions/experimental.html
Майкл Леви,
10

Я бы использовал @deprecatedпо чисто практическим соображениям.

Хотя @deprecatedон и не дает точного значения, которое вы хотели бы получить, у него есть существенное преимущество: компилятор Java имеет встроенную поддержку. Компиляция с -deprecationфлагом позволяет найти все места, где вы переопределяете устаревший метод, помогая вашим пользователям очень быстро находить подозрительный код. Вы можете использовать @deprecatedтег Javadoc, чтобы объяснить, что на самом деле происходит, всем, кто хочет прочитать вашу документацию. Здесь вы можете сказать пользователю, что API является экспериментальным, его следует использовать на свой страх и риск и так далее.

dasblinkenlight
источник
1
+1. Отличный момент. Наличие встроенной поддержки очень важно для таких частей API и поощряет пользователей просматривать документацию, чтобы понять, почему эти части помечены как устаревшие.
Арсений Мурзенко
2
Я склонялся к чему-то вроде «* @deprecated. Это экспериментальный API, и он, вероятно, изменится» как минимум, чтобы IDE и документы могли выделить метод, а затем получить краткое объяснение.
Майкл Леви
Просто запомни, что устарелым будет много предупреждений. Это может быть не так плохо, как кажется. Быть предупрежденным об экспериментальных особенностях могло быть хорошо.
Борхаб,
3

Я никогда не видел ничего подобного в других API, поскольку экспериментальные или неполные функции не имеют ничего общего с публичным API.

Поскольку у вас нет выбора, просто поместите четко видимое предупреждение о том, что часть API может быть изменена.

Арсений Мурзенко
источник
Что ж. Например, у нас есть: junit.org/apidocs/org/junit/experimental/package-summary.html Кстати, использование пакета было отличной идеей. Если API работает нестабильно, вам нужно изменить пакет, чтобы нарушить все зависимости. Ява аннотация была бы намного лучше
Borjab