Как используются поля модуля Haddock, "Переносимость", "Стабильность" и "Поддержка"?

В большом количестве сгенерированной документации по Haddock (например, Prelude), в правом верхнем углу виден небольшой прямоугольник, содержащий информацию о переносимости, стабильности и сопровождающем:

Пример информационного пакета

Посмотрев исходный код на такие модули и экспериментируя, я подтвердил, что эта информация генерируется из строк, подобных приведенным ниже в описании модуля:

-- Maintainer  :  libraries@haskell.org
-- Stability   :  stable
-- Portability :  portable

В этом есть несколько странных вещей:

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

  • Мне не удалось найти официальную документацию по этим полям. Существует свойство пакета Cabal с именем stability, примеры значений которых соответствуют значениям, которые я видел в эквивалентных полях Хэддока, но кроме этого я ничего не нашел.

Итак: Как эти поля предназначены для использования и документированы ли они где-нибудь?

В частности, я хотел бы знать:

  • Полный список часто используемых значений для Portability а также Stability, На этой странице HaskellWiki есть список, но я хотел бы знать, откуда появился этот список.

  • Критерии принятия решения, является ли модуль переносным или непереносимым. В частности, пакет, для которого я хотел бы получить ответы на эти вопросы, acme-strfry, является связующим звеном FFI strfry, функция доступна только в glibc. Является ли пакет непереносимым, потому что он работает только на системах glibc, или переносимым, потому что он не использует какие-либо расширения языка Haskell? Общее использование, кажется, подразумевает последнее.

  • Почему требуется определенный порядок полей в исходном файле, и почему это противоположно порядку в сгенерированной документации.

Источник

2 ответа

Решение

О, я думал, что эти поля были из описания пакета клики. Похоже, они вообще не документированы в документах Хэддока. Я нашел это, что на самом деле не отвечает на ваш вопрос, но:

http://trac.haskell.org/haddock/ticket/71

Так что, если в любом случае это произвольная форма, почему бы просто не написать "непереносимый (зависит от glibc)"? Я видел даже "портативный (зависит от GHC)", что странно. Мне также интересно, что происходит с модулями, которые были непереносимыми из-за расширения Foo, отличного от Haskell98, после добавления Foo в Haskell 2010.

Обратите внимание, что документация Cabal, на которую вы ссылаетесь, также говорит, что стабильность является свободной формой. Конечно, даже если бы пикша или клика должны были определить приемлемые значения, сопровождающий все же должен был бы выбрать субъективно.

О конкретном порядке, вы, вероятно, должны просто спросить в списке рассылки пикши, или проверить источник и сообщить об ошибке.

PS: strfry - неоценимый вклад в сообщество Haskell, но он должен быть чистым и переносимым, не так ли?

Источник

Ах, да, одна из самых неясных и грубых черт Хэддока.

Насколько я могу судить, это просто недокументированный взлом. Нет никакой разумной причины, почему порядок полей должен иметь значение, но это имеет значение. Определенный выбор форматирования (т. Е. В виде специальной формы внутри комментария модуля, а не в виде отдельного блока) также не является лучшим. Я предполагаю, что кто-то хотел быстро добавить эту функцию однажды, поэтому они взломали что-то минимальное, но работающее, и оставили это в покое. (Не удосужившись документировать это.)

Лично я просто не занимаюсь этими полями вообще. Информация доступна от Cabal, поэтому я не буду дублировать ее и в Haddock. Возможно, однажды Кабал передаст эту информацию Хэддоку автоматически...

Источник
Другие вопросы по тегам