New annotation request: @include

[yaitskov]

Hi,

Sometimes function has complex type signature. Developer would like to define an "alias" with type aliases in the signature to make the function type more concise, but haddock of base function is not included. He could write a simple haddock with just a link to base function, but it has a drawback, because haddock content, besides conventional html page, is actively consumed through VSCode hover-triggered hints (plus as for now links to functions is not clickable), so even if hint content has a working link - he has to click to see informative haddock.

Functions specialized in such a way might appear more often in code base.

I suggest to introduce a new annotation @include <function or type name>, which tells haddock to append haddock of that function to the haddock of current one.

Also alternative semi-automatic behavior might be good - haddock of parent function is included if function body is just 1 identifier and doesn't have own haddocks e.g:

-- | 'any1' returns value 1 of any type castable to Num
any1 :: Num a => a
any1 = 1

int1 :: Int
int1 = any1

[Kleidukos]

Thanks a lot for the suggestion. :)

[yaitskov]

In GHC9 a workaround with TH is available, but it is limited to source functions defined in the same package, at least I have such experience with GHC-9.2.5 and cabal haddock --haddock-all:

appendHaddocksFrom ::
  Name -> -- ^ sourceName
  Name -> -- ^ targetName
  Q [Dec]
appendHaddocksFrom sourceName targetName = do
  addModFinalizer $ do
    srcDocsM <- getDoc $ DeclDoc sourceName
    case srcDocsM of
      Nothing -> do
        runIO (putStrLn $ "no src docs (" <> show sourceName <> ")")
        pure ()
      Just sd -> do
        targetDocs <- fromMaybe "" <$> getDoc target
        runIO (putStrLn $ "target docs: (" <> show target <> "):\n" <> targetDocs)
        putDoc target $ targetDocs <>
          "\n\n### __Following snippet is included from__ " <>
          nameRef sourceName <> "\n\n" <> sd
  pure []
  where
    target = DeclDoc targetName

module SupModule where
-- | 'foo' has haddocks in public domain
foo :: Int
foo = 3

module Module where
import SupModule
bar :: Int
bar = foo
$(appendHaddocksFrom 'foo 'bar)

[Kleidukos]

I'm closing this for now, Haddock has migrated to GitLab