You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository has been archived by the owner on Aug 3, 2024. It is now read-only.
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
The text was updated successfully, but these errors were encountered:
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)
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:
The text was updated successfully, but these errors were encountered: