haddock-use-refs (empty) → 1.0.1

raw patch · 9 files changed

+244/−0 lines, 9 filesdep +basedep +cpphsdep +haddock-library

Dependencies added: base, cpphs, haddock-library, haddock-use-refs, tasty, tasty-discover, tasty-hunit, tasty-quickcheck, template-haskell

Files

• LICENSE +30/−0
• changelog.md +3/−0
• haddock-use-refs.cabal +117/−0
• src/Haddock/UseRefs.hs +5/−0
• src/Haddock/UseRefs/Internal.hs +49/−0
• src/Haddock/UseRefs/Type.hs +9/−0
• test/Discovery.hs +1/−0
• test/Driver.hs +12/−0
• test/Haddock/UseRefs/Test.hs +18/−0

@@ -0,0 +1,30 @@+Copyright (c) 2025 Daniil Iaitskov+All rights reserved.++Redistribution and use in source and binary forms, with or without+modification, are permitted provided that the following conditions are+met:++    * Redistributions of source code must retain the above copyright+      notice, this list of conditions and the following disclaimer.++    * Redistributions in binary form must reproduce the above+      copyright notice, this list of conditions and the following+      disclaimer in the documentation and/or other materials provided+      with the distribution.++    * Neither the name of Edward Kmett nor the names of other+      contributors may be used to endorse or promote products derived+      from this software without specific prior written permission.++THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

@@ -0,0 +1,3 @@+# Haddock-use-refs changelog++## Version 1.0.0 2025-03-12

@@ -0,0 +1,117 @@+cabal-version:   3.0+name:            haddock-use-refs+version:         1.0.1+license:         BSD-3-Clause+license-file:    LICENSE+category:        Development+author:          Daniil Iaitskov <dyaitskov@gmail.com>+maintainer:      Daniil Iaitskov <dyaitskov@gmail.com>+stability:       experimental+synopsis:        Eliminate warnings for names referred in Haddock only+homepage:        https://github.com/yaitskov/haddock-use-refs+bug-reports:     https://github.com/yaitskov/haddock-use-refs/issues+build-type:      Simple+description:+    +    Haddock syntax supports+    <https://haskell-haddock.readthedocs.io/latest/markup.html#hyperlinked-identifiers hyper links>+    to functions and types mentioned in comments (an identifier enclosed in+    single quotes). The link is inserted only if the name is fully qualified+    or imported in the module. Names referred only in module documentation+    pose a problem in form of compiler warning about unused imports.+    +    This library helps with resolving these warnings authomatically without+    disabling all warnings of such type via a TH macro+    <https://hackage.haskell.org/package/haddock-use-refs/docs/Haddock-UseRefs.html#v:countDocRefs countDockRefs>,+    which discovers all names in module documentation and generates a dummy+    type with an instance+    <https://hackage.haskell.org/package/haddock-use-refs/docs/Haddock-UseRefs.html#t:CountHaddockRefs CountHaddockRefs>+    using all names in the method.+    +    > {-# OPTIONS_GHC -Wall -Werror #-}+    > {-# LANGUAGE TemplateHaskell #-}+    > module Module where+    >+    > import Haddock.UseRefs+    > import System.IO.Unsafe (unsafePerformIO)+    >+    > countDocRefs+    >+    > -- | 'unsafePerformIO' is not used by 'foo'.+    > foo :: Bool+    > foo = True+    +    The library does not require any configuration.++tested-with:+  GHC == 9.10.1+extra-doc-files:+  changelog.md+library+  build-depends:+    base < 5,+    cpphs < 2.0,+    haddock-library < 1.13,+    template-haskell < 2.24.0.0,++  exposed-modules:+    Haddock.UseRefs+    Haddock.UseRefs.Type+    Haddock.UseRefs.Internal++  ghc-options: -Wall+  hs-source-dirs: src+  default-language: Haskell2010+  default-extensions:+    BangPatterns+    DataKinds+    DeriveGeneric+    DeriveLift+    DisambiguateRecordFields+    DuplicateRecordFields+    FlexibleContexts+    FlexibleInstances+    ImportQualifiedPost+    LambdaCase+    MultiParamTypeClasses+    OverloadedLabels+    ScopedTypeVariables+    StandaloneDeriving+    TemplateHaskell+    TypeApplications+    TypeFamilies++test-suite test+  type: exitcode-stdio-1.0+  main-is: Driver.hs+  other-modules:+    Haddock.UseRefs.Test+    Discovery+    Paths_haddock_use_refs+  autogen-modules:+    Paths_haddock_use_refs+  hs-source-dirs:+    test+  default-extensions:+    DuplicateRecordFields+    FlexibleContexts+    ImportQualifiedPost+    LambdaCase+    OverloadedLabels+    RecordWildCards+    ScopedTypeVariables+    TemplateHaskell+  ghc-options: -Wall -rtsopts -threaded -main-is Driver+  build-depends:+      base+    , tasty+    , tasty-discover+    , tasty-hunit+    , tasty-quickcheck+    , template-haskell+    , haddock-use-refs+  default-language: Haskell2010++source-repository head+  type:     git+  location: https://github.com/yaitskov/haddock-use-refs.git

@@ -0,0 +1,5 @@+-- | The root module to be imported by applications and libraries.+module Haddock.UseRefs (module M) where++import Haddock.UseRefs.Type as M+import Haddock.UseRefs.Internal as M

@@ -0,0 +1,49 @@+{-# OPTIONS_HADDOCK hide, prune #-}+{-# OPTIONS_GHC -Wno-orphans #-}+{-# LANGUAGE CPP, DeriveLift #-}+module Haddock.UseRefs.Internal where++import Data.Maybe (catMaybes)+import Documentation.Haddock.Parser+import Haddock.UseRefs.Type+import Language.Haskell.TH+import Language.Haskell.TH.Syntax+import Language.Preprocessor.Cpphs (runCpphs, defaultCpphsOptions)++#if !MIN_VERSION_template_haskell(2,23,0)+deriving instance Lift OccName+deriving instance Lift ModName+deriving instance Lift PkgName+deriving instance Lift NameSpace+deriving instance Lift NameFlavour+deriving instance Lift Name+#endif++-- | Call in module with names mentioned only in documentation to+-- avoid warnings.+countDocRefs :: Q [Dec]+countDocRefs = do+  fp <- loc_filename  <$> location+  ids <- extractQuotedStrings <$> loadSource fp+  [d|+   data HaddockRefsCounter+   instance CountHaddockRefs HaddockRefsCounter where+     countHaddockRefs _ = length $(lift =<< lookupNames ids)+   |]+  where+    loadSource fp = runIO (runCpphs defaultCpphsOptions fp =<< readFile fp)++-- | Extract quoted strings from Haddock comment+extractQuotedStrings ::+  String -> -- ^ Haskell source code+  [String]+extractQuotedStrings = foldl' (\b i -> i : b) [] . toRegular  . parseString+++-- | Filter and resolve strings into type/value TH 'Language.Haskell.TH.Syntax.Name'.+lookupNames :: [String] -> Q [Name]+lookupNames ns = catMaybes <$> mapM lookupX ns+  where+    lookupX s = lookupTypeName s >>= \case+      Nothing -> lookupValueName s+      Just tn -> pure $ Just tn

@@ -0,0 +1,9 @@+{-# OPTIONS_HADDOCK hide #-}+module Haddock.UseRefs.Type where++import Data.Proxy+import Prelude++-- | Type and instance is generated by 'Haddock.UseRefs.countDocRefs'+class CountHaddockRefs a where+  countHaddockRefs :: Proxy a -> Int

@@ -0,0 +1,1 @@+{-# OPTIONS_GHC -F -pgmF tasty-discover -optF --generated-module=Discovery #-}

@@ -0,0 +1,12 @@+module Driver where++import qualified Discovery+import Test.Tasty++main :: IO ()+main = defaultMain =<< testTree+  where+    testTree :: IO TestTree+    testTree = do+      tests <- Discovery.tests+      pure $ testGroup "haddock-use-refs" [ tests ]

@@ -0,0 +1,18 @@+{-# OPTIONS_GHC -Wall -Werror #-}+{-# LANGUAGE CPP, TemplateHaskell #-}++-- | Module refers 'M.join'.+module Haddock.UseRefs.Test where++import Control.Monad qualified as M+import System.IO.Unsafe (unsafePerformIO)+import Haddock.UseRefs++#if !MIN_VERSION_base(4,8,0)+#endif++countDocRefs++-- | 'unsafePerformIO' is not used by 'foo'.+prop_foo :: Bool+prop_foo = True