haskell - ¿Cómo se utilizan los campos del módulo Haddock Portabilidad, Estabilidad y Mantenimiento?

Question

En la documentación del módulo generado por Haddock (por ejemplo, Prelude ), se puede ver una pequeña caja en la parte superior derecha, que contiene portabilidad, estabilidad e información del mantenedor:

Desde la observación del código fuente hasta dichos módulos y la experimentación, confirmé que esta información se genera a partir de líneas como las siguientes en la descripción del módulo:

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

Hay varias cosas extrañas sobre esto:

• Los campos solo parecen funcionar en este orden: cualquier campo que no esté en orden se trata simplemente como parte de la descripción del módulo. ¡A pesar del hecho de que el orden en el archivo fuente es el opuesto al orden en la documentación generada!

• No he podido encontrar ninguna documentación oficial de estos campos. Hay una propiedad del paquete Cabal llamada stability , cuyos valores de ejemplo coinciden con los valores que he visto en los campos de Haddock equivalentes, pero más allá de eso, no he encontrado nada.

Entonces: ¿cómo se pretende que se usen estos campos, y están documentados en cualquier lugar?

En particular, me gustaría saber:

• La lista completa de valores de uso común para la Portability y la Stability . Esta página de HaskellWiki tiene una lista, pero me gustaría saber de dónde se originó esta lista.

• Los criterios para decidir si un módulo es portátil o no portátil. En particular, el paquete para el que me gustaría acme-strfry las respuestas a estas preguntas, acme-strfry , es un enlace FFI a strfry , una función solo disponible en glibc. ¿El paquete no es portátil porque solo funciona en sistemas glibc o portátil porque no usa ninguna extensión de lenguaje Haskell? El uso común parece implicar lo segundo.

• Por qué se requiere un orden específico de campos en el archivo de origen, y por qué es lo opuesto al ordenamiento en la documentación generada.

Answer 1

Ah, sí, una de las características más oscuras y crufty de Haddock.

Lo mejor que puedo decir, es solo un hack indocumentado. No hay ninguna razón sensata por la que el orden de los campos deba importar, pero lo hace. La opción específica de formato (es decir, como una forma especial dentro del comentario del módulo en lugar de como un bloque separado de algún tipo) tampoco es la mejor. Supongo que alguien quiso agregar rápidamente esta función un día, por lo que hackearon algo mínimo pero funcionó, y lo dejaron así. (Sin molestarse en documentarlo).

Personalmente, simplemente no me molesto en estos campos en absoluto. La información está disponible en Cabal, así que tampoco me molesto en duplicarla en Haddock. Quizás algún día Cabal pasará esta información a Haddock automáticamente ...

Answer 2

Oh, pensé que esos campos eran de la descripción del paquete cabal. No parecen estar documentados en absoluto en los documentos de Haddock. He encontrado esto, que realmente no responde a tu pregunta, pero:

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

Entonces, si es de forma libre, ¿por qué no escribir "no portátil (depende de glibc)"? He visto incluso "portátil (depende de ghc)", lo cual es extraño. También me pregunto qué sucede con los módulos que no eran portátiles debido a la extensión que no es Haskell98, Foo, después de que Foo se agregara a Haskell 2010.

Tenga en cuenta que la documentación de Cabal a la que se vincula también dice que la estabilidad es de forma libre. Por supuesto, incluso si el eglefino o la camarilla definieran cuáles son los valores aceptables, todavía estaría en manos del mantenedor seleccionar uno subjetivamente.

Sobre el orden específico, probablemente debería preguntar en la lista de correo de eglefino, o verificar la fuente y presentar un error.

PS: strfry es una contribución invaluable a la comunidad Haskell, pero debería ser pura y portátil, ¿no crees?