Haddock: Dokumentacja dla funkcji instancji z dziwactw zastąpione domyślną klasy dokumentacji

Question

Rozważmy następujący przykład:

instance (Monad m) => MonadState s (ChronoT s e m) where 

    -- | Returns the present-day state. 
    get = ChronoT $ do 
     (ChronoS _ s _) <- get 
     return s 

    -- | Set the present-day state directly, erasing the past and future for 
    -- safety. See also 'paradox'. 
    put x = ChronoT $ do 
     (ChronoS _ _ _) <- get 
     put $ mkChronoS x 

Po uruchomieniu przez plamiaka, funkcje get i put pokazać się, ale są one za pomocą dokumentacji domyślną z MonadState . Jak dołączyć do nich moją dokumentację w moim module?

(Można zobaczyć, co mam na myśli, uruchamiając cabal haddock nad repo here)

Answer 1

nie można.

Co można zrobić, to udokumentować swoje wystąpienie.

-- | You can have a brief description here 
instance (Monad m) => MonadState s (ChronoT s e m) where 
… 

To sprawi, że opis pojawi się na stronie okna instances wygenerowane. Powinno to być krótkie, ale pozwala ci robić takie rzeczy, jak wskazanie użytkownikowi dokumentacji funkcji implementujących pola, jeśli naprawdę potrzebujesz, tak jak sugeruje komentator na pytanie.

Osobiście uważam, że nie ma większego sensu dokumentowanie każdego pola w następujący sposób: to, co pola mają wykonywać, powinno być jasne z dokumentacji definicji klasy i komentarza do instancji.