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

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

An example package information box

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

-- Maintainer  :  [email protected]
-- Stability   :  stable
-- Portability :  portable

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

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

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

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

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

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

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

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

Ответы

Ответ 1

О, я думал, что эти поля были из описания пакета. Как правило, они не документируются документами Haddock. Я нашел это, что на самом деле не отвечает на ваш вопрос, но:

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

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

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

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

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

Ответ 2

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

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

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