Suppose I have a Haskell module named MyModule that imports an external module like this:
import ModuleA hiding (a, b, c)
And I cannot modify this import statement, because the program is not exactly mine.
I wish to link to ModuleA.external_function in the documentation for ModuleA, in the comments above a function called my_function. So the code looks something like this:
-- | my_function makes use of 'ModuleA.external_function'
my_function :: Int -> Int
Using haddock 2.10.0, and running cabal haddock, the link to ModuleA.external_function is generated as dist/doc/html/MyModule/ModuleA.html#v:external_function . However, the problem is that the dist/doc/html/MyModule/ModuleA.html file does not exist.
How can I generate a link to the docs for ModuleA instead, like module-A-package/docs/ModuleA.html#v:external_function. In other words, something similar to what http://hackage.haskell.org/package/text-0.11.2.0/docs/Data-Text.html has for its links to the String type (they link to http://hackage.haskell.org/package/base-4.5.0.0/docs/Data-String.html#t:String)? Bear in mind that I cannot modify the import statement.
Thank you.
To make links to external packages in the Haddock documentation, you need to instruct it where to find the documentation for those packages.
It is done by using the --read-interface Haddock command-line option.
Using your example, it will be :
haddock --read-interface module-A-package/docs/,module-A-package/docs/module-A-package.haddock
The .haddock file is made when generating documentation for the package module-A-package using ----dump-interface Haddock command-line option.
More information can be found on the Haddock documentation or this HaskellWiki page.
Related
I would like to look at the code of functions defined in modules, such as Data.List or Data.Map.
I can import Data.List module with
import Data.List
and then I can use the functions nub or sort.
I would like to know where I can find these functions to look at their code.
In which directory are the modules installed by default?
PS: Windows 8.1, I installed Haskell Platform.
That directory contains compiled modules, so you wouldn't be able to read the source there.
What you can do is to find your function in online documentation and then click "Source" on the right.
As #arrowd notes in his answer,
That directory contains compiled modules, so you wouldn't be able to
read the source there.
The GHC repo (and its Github mirror) can be directly browsed, but there is an easier way:
Use Hoogle or Stackage to find the package where the module/function resides
Note that Hoogle and Stackage are case-sensitive. (It's best to look up modules with their capitalized names.)
A query for sort in Hoogle yields a list similar to the one below. Stackage has a slightly different style, but the basics are the same (mostly because it uses Hoogle for lookup). The lines in green under the result headings show the name(s) of the containing
(1) package(s) (in small caps) and
(2) module(s) (capitalized).
There can be multiple functions with the same name, but the module and package name helps to choose the right one.
Click on the function/module name
Click on "#Source"
I am trying to generate documentations for a github library using haddock. Here's the code I entered:
$ find -name '*.hs' | xargs haddock --html -o docs
src/Reflex/Dom/Xhr.hs:154:0:
error: missing binary operator before token "("
#if MIN_VERSION_aeson(1,0,0)
^
Then I looked up the relevant section of my source code Xhr.hs line 154:
import Data.Aeson
#if MIN_VERSION_aeson(1,0,0)
import Data.Aeson.Text
#else
import Data.Aeson.Encode
#endif
I didn't know #if, #else and #endif were part of Haskell but I could guess the meaning. Depending on the version, the code should import either Aeson.Text or Aeson.Encode. Just in case, I looked up the version:
$ ghc-pkg list | grep aeson
aeson-0.11.3.0
This was enough to give haddock difficulty. The info pages get sent to a folder called docs which contains a few empty html files waiting to be populated with the details of the Reflex.Dom library.
That code uses -cpp. Preprocessor directives are not part of the usual Haskell language. In order to correctly parse that code, you need to specify additional options to Haddock:
2.1. Using literate or pre-processed source
Since Haddock uses GHC internally, both plain and literate Haskell sources are accepted without the need for the user to do anything. To use the C pre-processor, however, the user must pass the the -cpp option to GHC using --optghc. [emphasis mine]
There are two problems, though. C preprocessor macro expansion you've posted will only work with GHC 8.0 (or later) if the package is exposed. It should, however, work with cabal haddock or stack haddock regardless of GHC's version. The latter variants are recommended if you try to build the documentation of a cabal/stack package, by the way.
If you still know what you're doing, use haddock --optghc=-cpp.
I am the author of the operational package, which includes example code. I would like this example code to be hscolored and installed together with the API documentation, which is generated by Haddock.
I probably have to use a custom Cabal build type and create a user hook for the Haddock phase. However, I never managed to make this work. Hence, my question is:
How to include full modules as example code in Haddock?
Could you give an example of a Cabal user hook that applies hscolor to an additional source code file example.hs and joins the result with the generated Haddock documentation?
I'm a total Haskell nube and this is a shot in the dark, but couldn't you use hscolour to output the code as HTML and then do something along the lines of cabal haddock --executables --hyperlink-source to include the colorized HTML?
Im writing app in haskell and I would like to export some functions and datatypes to other files and then be able to use them in my main file.
How to do this ?
thanks for help
You could lay out your source code like so:
Main.hs
A/Module.hs
You need to specify in A/Module.hs which module it actually is; it has to be:
module A.Module where
...
In Main.hs, you import A.Module; all names are exported by default.
The Wikibooks page on Haskell modules would be a good starting point, or the relevant section of Learn You a Haskell (especially the "Making our own modules" part).
I'm trying to write a program that will check the file type of a certain file and I found a haskell library that should do the trick.
The problem arises when I try to use it. I have no idea what I have to do, which function to call etc. The library is full of cryptic commands with no examples, no tutorial or a homepage.
Please help.
There is the package's documentation that contains short descriptions of the important functions (which are not that many). For additional information about what the underlying C library does (and therefore also the Haskell library), have a look at libmagic's man page.
The basic usage should look similar to this (untested):
import Magic.Init
import Magic.Operations
main =
do magic <- magicOpen []
loadDefaultMagic magic
magicFile magic "/my/file" >>= print