16

Haddockで生成されたモジュールのドキュメントの多く（例Prelude）では、右上に小さなボックスがあり、移植性、安定性、およびメンテナ情報が含まれています。

パッケージ情報ボックスの例

ソースコードからそのようなモジュールや実験まで、この情報がモジュールの説明の次のような行から生成されていることを確認しました。

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

これにはいくつかの奇妙なことがあります：

  • フィールドはこの順序でのみ機能するように見えます。順序が狂っているフィールドは、モジュールの説明自体の一部として扱われるだけです。これは、ソースファイルの順序が、生成されたドキュメントの順序と逆であるという事実にも関わらずです。

  • これらの分野の公式文書を見つけることができませんでした。、という名前のCabalパッケージプロパティがありstability、そのサンプル値は、同等のHaddockフィールドで見た値と一致しますが、それを超えると、何も見つかりませんでした。

したがって、これらのフィールドはどのように使用されることを意図しており、どこにでも文書化されていますか？

特に、私は知りたいです：

  • Portabilityおよびの一般的に使用される値の完全なリストStability。このHaskellWikiページにはリストがありますが、このリストの出所を知りたいのですが。

  • モジュールがポータブルか非ポータブルかを判断するための基準。特に、 acme-strfryに対するこれらの質問への回答を希望するパッケージはstrfry、glibcでのみ使用可能な関数であるへのFFIバインディングです。パッケージはglibcシステムでのみ動作するため、移植性がありませんか、それともHaskell言語拡張を使用しないため、移植性がありますか？一般的な使用法は後者を意味するようです。

  • ソースファイルでフィールドの特定の順序が必要な理由、および生成されたドキュメントの順序とは逆の理由。

4

2 に答える 2

4

ああ、それらのフィールドはカバールパッケージの説明からのものだと思いました。それらはHaddockのドキュメントにまったく文書化されていないようです。私はこれを見つけました、それはあなたの質問に実際には答えませんが：

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

それで、とにかくそれが自由形式であるならば、なぜ単に「移植性がない（glibcに依存する）」と書いてみませんか？奇妙な「ポータブル（ghcに依存）」も見たことがあります。また、FooがHaskell 2010に追加された後、Haskell98拡張機能Fooがないために移植できなかったモジュールはどうなるのだろうか。

リンク先のCabalのドキュメントには、安定性は自由形式であるとも記載されていることに注意してください。もちろん、ハドックやカバルが許容値を定義したとしても、主観的に選択するのは保守者の責任です。

具体的な注文については、おそらくハドックのメーリングリストで質問するか、ソースを確認してバグを報告する必要があります。

PS：strfryはHaskellコミュニティへのかけがえのない貢献ですが、純粋でポータブルでなければなりませんね。

于 2012-01-26T06:34:34.283 に答える
3

ああ、そうです、Haddockのよりあいまいで無愛想な機能の1つです。

私が知る限り、それは文書化されていないハックです。フィールドの順序が重要であるという正当な理由はありませんが、重要です。フォーマットの特定の選択（つまり、ある種の個別のブロックとしてではなく、モジュールコメント内の特別なフォームとして）も最適ではありません。私の推測では、誰かがこの機能をいつかすぐに追加したいと思ったので、彼らは最小限であるが機能しているものをハックして、それをそのままにしました。（わざわざ文書化することなく。）

個人的には、これらのフィールドをまったく気にしません。情報はCabalから入手できるので、Haddockでもわざわざ複製する必要はありません。おそらくいつかCabalはこの情報をHaddockに自動的に渡すでしょう...

于 2012-01-26T10:26:09.043 に答える