JEP draft: Guidelines for documenting system properties

Аннотация

В этом информационном JEP изложены рекомендации по документированию системных свойств в документации API.

Мотивация

Системные свойства в документации API Java SE и JDK описаны очень по-разному: от таблиц, как в документации метода System.getProperties(), до простых упоминаний, как у java.util.secureRandomSeed в ThreadLocalRandom и SplittableRandom.

Новый тег документационного комментария {@systemProperty property-name}, появившийся в JDK 12, упрощает поиск системных свойств, но не определяет, что значит правильно задокументировать системное свойство. При этом многие системные свойства считаются признанным системным интерфейсом и отслеживаются в процессе Compatibility and Specification Review (CSR). Определяющие характеристики конкретного системного свойства выходят за рамки тега документационного комментария, и описывать их лучше всего в спецификации соответствующего API. Но, хотя формального способа специфицировать системное свойство может и не быть, при написании спецификации свойства стоит учесть ряд характеристик.

Этот JEP задуман как справочник для тех, кто определяет новые системные свойства или обновляет спецификацию существующих.

Характеристики

• Именование: системные свойства обычно называют идентификаторами с точками. Группа связанных системных свойств обычно имеет общий префикс. Идентификаторы, начинающиеся с java., предназначены для спецификаций, контролируемых JCP. Идентификаторы, начинающиеся с jdk., предназначены для спецификаций JDK.

• Значения: тип и/или множество допустимых значений нужно указывать всегда. Например, boolean, строка, int, путь в файловой системе, URL, дата и так далее. Для типа boolean укажите, какие значения соответствуют true и false.

  • Ограничения на значения: укажите все ограничения на множество допустимых значений. Например, ограничен ли диапазон допустимых целых значений; обозначает ли путь к файлу каталог или существующий файл?

  • Пустые значения: допускаются ли пустые или незаданные значения, и если да, как они обрабатываются?

  • Недопустимые значения: как обрабатывается недопустимое значение? Оно игнорируется или выдаётся ошибка?

  • Как задаётся значение свойства? Значение задаёт система или обычно его задаёт пользователь — либо параметром командной строки -Dname=value, либо с помощью System.setProperty.

  • Изменяемость: можно ли изменить значение? Если нельзя, что произойдёт при попытке его изменить? Такие попытки игнорируются или выдаётся ошибка?

  • Время чтения: когда считывается значение? Кэшируется ли оно, и если да, то когда? Например, кэшируется ли оно до вызова главной точки входа приложения? Если значение кэшируется, что произойдёт при последующей попытке его изменить?

• Платформы: если системное свойство определено только для использования на определённых платформах, укажите эти платформы.

• Область действия: какова область действия свойства? Является ли оно частью спецификации Java SE, спецификации JDK или какой-либо другой библиотеки? Учтите, что иногда наличие системного свойства относится к реализации некоторой спецификации и не должно считаться частью самой спецификации. В таких случаях определение свойства должно быть чётко и надлежащим образом помечено.

• Где: подумайте о том, чтобы разместить спецификацию системного свойства в наименьшей единице публичной документации, охватывающей API, которые предоставляют или используют это свойство. Например, если системное свойство всегда будет использоваться только одним конкретным методом, подумайте о том, чтобы разместить его спецификацию в спецификации этого метода. Если свойство будет использоваться всеми или многими типами модуля или пакета, подумайте о том, чтобы разместить спецификацию в спецификации модуля или пакета. Иногда метод, тип или пакет, предоставляющий системное свойство, сам может не входить в спецификацию публичного API. В таких случаях размещайте спецификацию в наименьшем объемлющем элементе, который входит в публичную спецификацию.

• Статус Deprecated (устаревший): если системное свойство помечено как Deprecated, приведите сведения об альтернативах, а также о том, будет ли удалена поддержка этого системного свойства и когда.

• Определение, ссылки: чётко отличайте спецификацию системного свойства от возможных ссылок на эту спецификацию. Каждое системное свойство должно определяться только в одном месте, но ссылок на эту спецификацию может быть много во всём связанном API.