Comentarios de eglefino sobre entidades importadas

¿Hay alguna forma de agregar la documentación de Haddock a una entidad en el módulo que la exporta, en lugar del que la declara?

Tengo un módulo oculto que declara una docena de tipos y luego otro módulo que exporta solo las partes que se supone que debe ver el usuario final. Sería lógico poner la documentación en el módulo expuesto en lugar del oculto. Pero no se como hacerlo...

preguntado el 31 de julio de 12 a las 10:07

Creo que tiene más sentido poner la documentación en el módulo donde se declaran los tipos. Haddock creará archivos doc con la estructura correcta para usted. Por ejemplo, si tiene un módulo Foo que exporta tipos A, B y C (con documentación) y módulo Bar que reexporta solamente A, luego los archivos doc para Bar automáticamente contendrá la documentación pertinente para A, copiado del módulo Foo. -

@ChrisTaylor Sé que lo hará trabajo, es sólo un poco poco elegante. Lo haré si no hay forma de evitarlo, pero primero quiero ver si hay una mejor manera. -

Apoyando a Chris Taylor. Cuando las personas estén leyendo su fuente, van a querer los documentos por el código; Creo que ese es el objetivo de mezclar el marcado de documentos y el código. Sugerencia relevante que acabo de aprender: si coloca algún código en un submódulo no exportado y desea hacer referencia a funciones de otro módulo no importado de su proyecto, puede proporcionar una ruta completa, como 'Control.Foo.bar' y eso aparecerá como un enlace con el texto "bar" -

2 Respuestas

No, no es posible. Las funciones pueden tener documentación por argumento y por parámetro de tipo, y haría que la documentación fuera inconsistente si pudiera:

  1. escribir diferentes versiones en diferentes lugares
  2. hacer que una versión anule a otra
  3. introducir inconsistencias en la documentación de los argumentos: ¿qué sucede si anula la cadena de documentación principal para una función? ¿Deberían eliminarse las cadenas de documentos del argumento?

El siguiente archivo:

module Bla
       ( -- * Fooishness

         -- | This is 'foo'. It is not 'bar'.
         foo
       , -- * Barishness

         -- | This is 'bar'. It is sometimes a little 'foo'.
         bar
       ) where

-- | The actual foo documentation
foo :: a -- ^ The a
    -> b -- ^ The b
    -> c
foo = undefined

-- | The actual bar documentation
bar :: a
bar = undefined

... produce esta documentación:

Documentación de eglefino

Como puede ver, puede usar comentarios de sección para emular cadenas de documentación de funciones, pero la documentación solo se generará correctamente si usa comentarios de documentación de funciones justo al lado de las firmas de tipo.

Respondido 31 Jul 12, 10:07

Para ser claros: no estoy tratando de escribir documentación diferente para la misma entidad. Solo quiero poner toda la documentación en un archivo, el módulo expuesto, porque parece más lógico. Sé que Haddock tiene una forma de ajustar el "módulo de inicio" para una entidad, no estaba seguro de si eso me permitiría hacer algo... - MatemáticaOrquídea

Bueno, ahora que lo pienso, podría escribir un newtype en el módulo expuesto. No conlleva una sobrecarga de tiempo de ejecución, solo hace que mi código sea un poco más desordenado...

Respondido 31 Jul 12, 10:07

No es la respuesta que estás buscando? Examinar otras preguntas etiquetadas or haz tu propia pregunta.