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

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

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

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

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

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

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

• Apache Incubator

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

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

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

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

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

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

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