Как используются поля модуля Haddock, «Переносимость», «Стабильность» и «Поддержка»? - PullRequest
Новая
       16

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

16 голосов
/ 26 января 2012

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

An example package information box

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

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

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

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

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

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

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

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

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

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

Ответы [ 2 ]

4 голосов
/ 26 января 2012

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

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

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

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

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

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

3 голосов
/ 26 января 2012

Ах, да, одна из самых неясных и хитрых особенностей Пикши.

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

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

...