path: root/org-test/ref/main.org

* 
  :PROPERTIES:
  :CUSTOM_ID: main
  :Hackage: https://hackage.haskell.org/package/main
  :END:



** Test
   :PROPERTIES:
   :CUSTOM_ID: main.Test
   :Hackage: https://hackage.haskell.org/package/main/docs/Test.html
   :END:

This module illustrates & tests most of the features of Haddock. Testing references from the description: [[#main.Test.T][T]], [[#main.Test.f][f]], [[#main.Test.g][g]], [[#main.Visible.visible][visible]].

*** Type declarations

**** Data types

***** data T a b
      :PROPERTIES:
      :CUSTOM_ID: main.Test.T
      :CUSTOM_ID: Test.T
      :END:

This comment applies to the /following/ declaration and it continues until the next non-comment line

****** A [[#base.Data.Int.Int][Int]] ([[#base.Data.Maybe.Maybe][Maybe]] [[#base.Prelude.Float][Float]])
       :PROPERTIES:
       :CUSTOM_ID: main.Test.A:dc
       :CUSTOM_ID: Test.A:dc
       :END:

This comment describes the [[#main.Test.A:dc][A]] constructor

****** B ([[#main.Test.T][T]] a b, [[#main.Test.T][T]] [[#base.Data.Int.Int][Int]] [[#base.Prelude.Float][Float]])
       :PROPERTIES:
       :CUSTOM_ID: main.Test.B:dc
       :CUSTOM_ID: Test.B:dc
       :END:

This comment describes the [[#main.Test.B:dc][B]] constructor

***** data T2 a b
      :PROPERTIES:
      :CUSTOM_ID: main.Test.T2
      :CUSTOM_ID: Test.T2
      :END:

An abstract data declaration

***** data T3 a b
      :PROPERTIES:
      :CUSTOM_ID: main.Test.T3
      :CUSTOM_ID: Test.T3
      :END:

A data declaration with no documentation annotations on the constructors

****** A1 a
       :PROPERTIES:
       :CUSTOM_ID: main.Test.A1:dc
       :CUSTOM_ID: Test.A1:dc
       :END:

****** B1 b
       :PROPERTIES:
       :CUSTOM_ID: main.Test.B1:dc
       :CUSTOM_ID: Test.B1:dc
       :END:

***** data T4 a b
      :PROPERTIES:
      :CUSTOM_ID: main.Test.T4
      :CUSTOM_ID: Test.T4
      :END:

****** A2 a
       :PROPERTIES:
       :CUSTOM_ID: main.Test.A2:dc
       :CUSTOM_ID: Test.A2:dc
       :END:

****** B2 b
       :PROPERTIES:
       :CUSTOM_ID: main.Test.B2:dc
       :CUSTOM_ID: Test.B2:dc
       :END:

***** data T5 a b
      :PROPERTIES:
      :CUSTOM_ID: main.Test.T5
      :CUSTOM_ID: Test.T5
      :END:

****** A3 a
       :PROPERTIES:
       :CUSTOM_ID: main.Test.A3:dc
       :CUSTOM_ID: Test.A3:dc
       :END:

documents [[#main.Test.A3:dc][A3]]

****** B3 b
       :PROPERTIES:
       :CUSTOM_ID: main.Test.B3:dc
       :CUSTOM_ID: Test.B3:dc
       :END:

documents [[#main.Test.B3:dc][B3]]

***** data T6
      :PROPERTIES:
      :CUSTOM_ID: main.Test.T6
      :CUSTOM_ID: Test.T6
      :END:

Testing alternative comment styles

****** A4
       :PROPERTIES:
       :CUSTOM_ID: main.Test.A4:dc
       :CUSTOM_ID: Test.A4:dc
       :END:

This is the doc for [[#main.Test.A4:dc][A4]]

****** B4
       :PROPERTIES:
       :CUSTOM_ID: main.Test.B4:dc
       :CUSTOM_ID: Test.B4:dc
       :END:

This is the doc for [[#main.Test.B4:dc][B4]]

****** C4
       :PROPERTIES:
       :CUSTOM_ID: main.Test.C4:dc
       :CUSTOM_ID: Test.C4:dc
       :END:

This is the doc for [[#main.Test.C4:dc][C4]]

***** newtype N1 a
      :PROPERTIES:
      :CUSTOM_ID: main.Test.N1
      :CUSTOM_ID: Test.N1
      :END:

A newtype

****** N1 a
       :PROPERTIES:
       :CUSTOM_ID: main.Test.N1:dc
       :CUSTOM_ID: Test.N1:dc
       :END:

***** newtype N2 a b
      :PROPERTIES:
      :CUSTOM_ID: main.Test.N2
      :CUSTOM_ID: Test.N2
      :END:

A newtype with a fieldname

****** N2 {
       :PROPERTIES:
       :CUSTOM_ID: main.Test.N2:dc
       :CUSTOM_ID: Test.N2:dc
       :END:

******* n :: a b
        :PROPERTIES:
        :CUSTOM_ID: main.Test.n
        :CUSTOM_ID: Test.n
        :END:

***** newtype N3 a b
      :PROPERTIES:
      :CUSTOM_ID: main.Test.N3
      :CUSTOM_ID: Test.N3
      :END:

A newtype with a fieldname, documentation on the field

****** N3 {
       :PROPERTIES:
       :CUSTOM_ID: main.Test.N3:dc
       :CUSTOM_ID: Test.N3:dc
       :END:

******* n3 :: a b
        :PROPERTIES:
        :CUSTOM_ID: main.Test.n3
        :CUSTOM_ID: Test.n3
        :END:

this is the [[#main.Test.n3][n3]] field

***** data N4 a b
      :PROPERTIES:
      :CUSTOM_ID: main.Test.N4
      :CUSTOM_ID: Test.N4
      :END:

An abstract newtype - we show this one as data rather than newtype because the difference isn't visible to the programmer for an abstract type.

***** newtype N5 a b
      :PROPERTIES:
      :CUSTOM_ID: main.Test.N5
      :CUSTOM_ID: Test.N5
      :END:

****** N5 {
       :PROPERTIES:
       :CUSTOM_ID: main.Test.N5:dc
       :CUSTOM_ID: Test.N5:dc
       :END:

******* n5 :: a b
        :PROPERTIES:
        :CUSTOM_ID: main.Test.n5
        :CUSTOM_ID: Test.n5
        :END:

no docs on the datatype or the constructor

***** newtype N6 a b
      :PROPERTIES:
      :CUSTOM_ID: main.Test.N6
      :CUSTOM_ID: Test.N6
      :END:

****** N6 {
       :PROPERTIES:
       :CUSTOM_ID: main.Test.N6:dc
       :CUSTOM_ID: Test.N6:dc
       :END:

docs on the constructor only

******* n6 :: a b
        :PROPERTIES:
        :CUSTOM_ID: main.Test.n6
        :CUSTOM_ID: Test.n6
        :END:

***** newtype N7 a b
      :PROPERTIES:
      :CUSTOM_ID: main.Test.N7
      :CUSTOM_ID: Test.N7
      :END:

docs on the newtype and the constructor

****** N7 {
       :PROPERTIES:
       :CUSTOM_ID: main.Test.N7:dc
       :CUSTOM_ID: Test.N7:dc
       :END:

The [[#main.Test.N7][N7]] constructor

******* n7 :: a b
        :PROPERTIES:
        :CUSTOM_ID: main.Test.n7
        :CUSTOM_ID: Test.n7
        :END:

**** Records

***** data R
      :PROPERTIES:
      :CUSTOM_ID: main.Test.R
      :CUSTOM_ID: Test.R
      :END:

This is the documentation for the [[#main.Test.R][R]] record, which has four fields, [[#main.Test.p][p]], [[#main.Test.q][q]], [[#main.Test.r][r]], and [[#main.Test.s][s]].

****** C1 {
       :PROPERTIES:
       :CUSTOM_ID: main.Test.C1:dc
       :CUSTOM_ID: Test.C1:dc
       :END:

This is the [[#main.Test.C1:dc][C1]] record constructor, with the following fields:

******* p :: [[#base.Data.Int.Int][Int]]
        :PROPERTIES:
        :CUSTOM_ID: main.Test.p
        :CUSTOM_ID: Test.p
        :END:

This comment applies to the [[#main.Test.p][p]] field

******* q :: forall a. a -> a
        :PROPERTIES:
        :CUSTOM_ID: main.Test.q
        :CUSTOM_ID: Test.q
        :END:

This comment applies to the [[#main.Test.q][q]] field

******* r, s :: [[#base.Data.Int.Int][Int]]
        :PROPERTIES:
        :CUSTOM_ID: main.Test.r
        :CUSTOM_ID: Test.r
        :CUSTOM_ID: main.Test.s
        :CUSTOM_ID: Test.s
        :END:

This comment applies to both [[#main.Test.r][r]] and [[#main.Test.s][s]]

****** C2 {
       :PROPERTIES:
       :CUSTOM_ID: main.Test.C2:dc
       :CUSTOM_ID: Test.C2:dc
       :END:

This is the [[#main.Test.C2:dc][C2]] record constructor, also with some fields:

******* t :: [[#main.Test.T1][T1]] -> ([[#main.Test.T2][T2]] [[#base.Data.Int.Int][Int]] [[#base.Data.Int.Int][Int]]) -> ([[#main.Test.T3][T3]] [[#base.Data.Bool.Bool][Bool]] [[#base.Data.Bool.Bool][Bool]]) -> ([[#main.Test.T4][T4]] [[#base.Prelude.Float][Float]] [[#base.Prelude.Float][Float]]) -> [[#main.Test.T5][T5]] () ()
        :PROPERTIES:
        :CUSTOM_ID: main.Test.t
        :CUSTOM_ID: Test.t
        :END:

******* u, v :: [[#base.Data.Int.Int][Int]]
        :PROPERTIES:
        :CUSTOM_ID: main.Test.u
        :CUSTOM_ID: Test.u
        :CUSTOM_ID: main.Test.v
        :CUSTOM_ID: Test.v
        :END:

***** data R1
      :PROPERTIES:
      :CUSTOM_ID: main.Test.R1
      :CUSTOM_ID: Test.R1
      :END:

Testing different record commenting styles

****** C3 {
       :PROPERTIES:
       :CUSTOM_ID: main.Test.C3:dc
       :CUSTOM_ID: Test.C3:dc
       :END:

This is the [[#main.Test.C3:dc][C3]] record constructor

******* s1 :: [[#base.Data.Int.Int][Int]]
        :PROPERTIES:
        :CUSTOM_ID: main.Test.s1
        :CUSTOM_ID: Test.s1
        :END:

The [[#main.Test.s1][s1]] record selector

******* s2 :: [[#base.Data.Int.Int][Int]]
        :PROPERTIES:
        :CUSTOM_ID: main.Test.s2
        :CUSTOM_ID: Test.s2
        :END:

The [[#main.Test.s2][s2]] record selector

******* s3 :: [[#base.Data.Int.Int][Int]]
        :PROPERTIES:
        :CUSTOM_ID: main.Test.s3
        :CUSTOM_ID: Test.s3
        :END:

The [[#main.Test.s3][s3]] record selector

test that we can export record selectors on their own:

***** p :: [[#main.Test.R][R]] -> [[#base.Data.Int.Int][Int]]
      :PROPERTIES:
      :CUSTOM_ID: main.Test.p
      :CUSTOM_ID: Test.p
      :END:

This comment applies to the [[#main.Test.p][p]] field

***** q :: [[#main.Test.R][R]] -> forall a. a -> a
      :PROPERTIES:
      :CUSTOM_ID: main.Test.q
      :CUSTOM_ID: Test.q
      :END:

This comment applies to the [[#main.Test.q][q]] field

***** u :: [[#main.Test.R][R]] -> [[#base.Data.Int.Int][Int]]
      :PROPERTIES:
      :CUSTOM_ID: main.Test.u
      :CUSTOM_ID: Test.u
      :END:

*** Class declarations

**** class ([[#main.Test.D][D]] a) => C a
     :PROPERTIES:
     :CUSTOM_ID: main.Test.C
     :CUSTOM_ID: Test.C
     :END:

This comment applies to the /previous/ declaration (the [[#main.Test.C][C]] class)

***** a :: [[#base.System.IO.IO][IO]] a
      :PROPERTIES:
      :CUSTOM_ID: main.Test.a
      :CUSTOM_ID: Test.a
      :END:

this is a description of the [[#main.Test.a][a]] method

***** b :: [a]
      :PROPERTIES:
      :CUSTOM_ID: main.Test.b
      :CUSTOM_ID: Test.b
      :END:

this is a description of the [[#main.Test.b][b]] method

**** class D a
     :PROPERTIES:
     :CUSTOM_ID: main.Test.D
     :CUSTOM_ID: Test.D
     :END:

This is a class declaration with no separate docs for the methods

***** d :: [[#main.Test.T][T]] a b
      :PROPERTIES:
      :CUSTOM_ID: main.Test.d
      :CUSTOM_ID: Test.d
      :END:

***** e :: (a, a)
      :PROPERTIES:
      :CUSTOM_ID: main.Test.e
      :CUSTOM_ID: Test.e
      :END:

***** Instances:

- [[#main.Test.D][D]] [[#base.Prelude.Float][Float]]
- [[#main.Test.D][D]] [[#base.Data.Int.Int][Int]]

**** class E a
     :PROPERTIES:
     :CUSTOM_ID: main.Test.E
     :CUSTOM_ID: Test.E
     :END:

This is a class declaration with no methods (or no methods exported)

**** class F a
     :PROPERTIES:
     :CUSTOM_ID: main.Test.F
     :CUSTOM_ID: Test.F
     :END:

***** ff :: a
      :PROPERTIES:
      :CUSTOM_ID: main.Test.ff
      :CUSTOM_ID: Test.ff
      :END:

Test that we can export a class method on its own:

**** a :: [[#main.Test.C][C]] a => [[#base.System.IO.IO][IO]] a
     :PROPERTIES:
     :CUSTOM_ID: main.Test.a
     :CUSTOM_ID: Test.a
     :END:

this is a description of the [[#main.Test.a][a]] method

*** Function types

**** f :: [[#main.Test.C][C]] a => a -> [[#base.Data.Int.Int][Int]]
     :PROPERTIES:
     :CUSTOM_ID: main.Test.f
     :CUSTOM_ID: Test.f
     :END:

In a comment string we can refer to identifiers in scope with single quotes like this: [[#main.Test.T][T]], and we can refer to modules by using double quotes: [[Foo]].  We can add emphasis /like this/.

- This is a bulleted list
- This is the next item (different kind of bullet)

1. This is an ordered list
2. This is the next item (different kind of bullet)

- cat :: a small, furry, domesticated mammal
- pineapple :: a fruit grown in the tropics

#+begin_src haskell
     This is a block of code, which can include other markup: R
     formatting
               is
                 significant
#+end_src

#+begin_src haskell
this is another block of code
#+end_src

We can also include URLs in documentation: [[http://www.haskell.org/]].

**** g :: [[#base.Data.Int.Int][Int]] -> [[#base.System.IO.IO][IO]] [[#main.Test.CInt][CInt]]
     :PROPERTIES:
     :CUSTOM_ID: main.Test.g
     :CUSTOM_ID: Test.g
     :END:

we can export foreign declarations too

*** Auxiliary stuff

This is some documentation that is attached to a name ($aux1) rather than a source declaration.  The documentation may be referred to in the export list using its name.

#+begin_src haskell
 code block in named doc
#+end_src

This is some documentation that is attached to a name ($aux2)

#+begin_src haskell
 code block on its own in named doc
#+end_src

#+begin_src haskell
 code block on its own in named doc (after newline)
#+end_src

a nested, named doc comment

with a paragraph,

#+begin_src haskell
 and a code block
#+end_src

#+begin_src haskell
test
test1
#+end_src

#+begin_src haskell
 test2
  test3
#+end_src

#+begin_src haskell
test1
test2
#+end_src

#+begin_src haskell
test3
test4
#+end_src

#+begin_src haskell
test1
test2
#+end_src

#+begin_src haskell
test3
test4
#+end_src

#+begin_src haskell
test3
test4
#+end_src

#+begin_src haskell
test1
test2
#+end_src

aux11:

#+begin_src haskell
test3
test4
#+end_src

#+begin_src haskell
test1
test2
#+end_src

#+begin_src haskell
foo
#+end_src

#+begin_src haskell
bar
#+end_src

This is some inline documentation in the export list

#+begin_src haskell
a code block using bird-tracks
each line must begin with > (which isn't significant unless it
is at the beginning of the line).
#+end_src

*** A hidden module

**** hidden :: [[#base.Data.Int.Int][Int]] -> [[#base.Data.Int.Int][Int]]
     :PROPERTIES:
     :CUSTOM_ID: main.Test.hidden
     :CUSTOM_ID: Test.hidden
     :END:

*** A visible module

**** module [[Visible]]

nested-style doc comments 

*** Existential / Universal types

**** data Ex a
     :PROPERTIES:
     :CUSTOM_ID: main.Test.Ex
     :CUSTOM_ID: Test.Ex
     :END:

A data-type using existential/universal types

***** forall b. [[#main.Test.C][C]] b => Ex1 b
      :PROPERTIES:
      :CUSTOM_ID: main.Test.Ex1:dc
      :CUSTOM_ID: Test.Ex1:dc
      :END:

***** forall b. Ex2 b
      :PROPERTIES:
      :CUSTOM_ID: main.Test.Ex2:dc
      :CUSTOM_ID: Test.Ex2:dc
      :END:

***** forall b. [[#main.Test.C][C]] a => Ex3 b
      :PROPERTIES:
      :CUSTOM_ID: main.Test.Ex3:dc
      :CUSTOM_ID: Test.Ex3:dc
      :END:

***** Ex4 (forall a. a -> a)
      :PROPERTIES:
      :CUSTOM_ID: main.Test.Ex4:dc
      :CUSTOM_ID: Test.Ex4:dc
      :END:

*** Type signatures with argument docs

**** k :: [[#main.Test.T][T]] () () -> [[#main.Test.T2][T2]] [[#base.Data.Int.Int][Int]] [[#base.Data.Int.Int][Int]] -> ([[#main.Test.T3][T3]] [[#base.Data.Bool.Bool][Bool]] [[#base.Data.Bool.Bool][Bool]] -> [[#main.Test.T4][T4]] [[#base.Prelude.Float][Float]] [[#base.Prelude.Float][Float]]) -> [[#main.Test.T5][T5]] () () -> [[#base.System.IO.IO][IO]] ()
     :PROPERTIES:
     :CUSTOM_ID: main.Test.k
     :CUSTOM_ID: Test.k
     :END:

Arguments:

- [[#main.Test.T][T]] () () :: This argument has type [[#main.Test.T][T]]
- ([[#main.Test.T2][T2]] [[#base.Data.Int.Int][Int]] [[#base.Data.Int.Int][Int]]) :: This argument has type 'T2 Int Int'
- ([[#main.Test.T3][T3]] [[#base.Data.Bool.Bool][Bool]] [[#base.Data.Bool.Bool][Bool]] -> [[#main.Test.T4][T4]] [[#base.Prelude.Float][Float]] [[#base.Prelude.Float][Float]]) :: This argument has type ~T3 Bool Bool -> T4 Float Float~
- [[#main.Test.T5][T5]] () () :: This argument has a very long description that should hopefully cause some wrapping to happen when it is finally rendered by Haddock in the generated HTML page.
- [[#base.System.IO.IO][IO]] () :: This is the result type

This is a function with documentation for each argument

**** l :: ([[#base.Data.Int.Int][Int]], [[#base.Data.Int.Int][Int]], [[#base.Prelude.Float][Float]]) -> [[#base.Data.Int.Int][Int]]
     :PROPERTIES:
     :CUSTOM_ID: main.Test.l
     :CUSTOM_ID: Test.l
     :END:

Arguments:

- ([[#base.Data.Int.Int][Int]], [[#base.Data.Int.Int][Int]], [[#base.Prelude.Float][Float]]) :: takes a triple
- [[#base.Data.Int.Int][Int]] :: returns an [[#base.Data.Int.Int][Int]]

**** m :: [[#main.Test.R][R]] -> [[#main.Test.N1][N1]] () -> [[#base.System.IO.IO][IO]] [[#base.Data.Int.Int][Int]]
     :PROPERTIES:
     :CUSTOM_ID: main.Test.m
     :CUSTOM_ID: Test.m
     :END:

Arguments:

- [[#main.Test.R][R]] :: 
- [[#main.Test.N1][N1]] () :: one of the arguments
- [[#base.System.IO.IO][IO]] [[#base.Data.Int.Int][Int]] :: and the return value

This function has some arg docs

**** o :: [[#base.Prelude.Float][Float]] -> [[#base.System.IO.IO][IO]] [[#base.Prelude.Float][Float]]
     :PROPERTIES:
     :CUSTOM_ID: main.Test.o
     :CUSTOM_ID: Test.o
     :END:

Arguments (in order):

1. The input float
2. The output float

A foreign import with argument docs

*** A section

**** A subsection

#+begin_src haskell
a literal line
#+end_src

$ a non /literal/ line $

***** f' :: [[#base.Data.Int.Int][Int]]
      :PROPERTIES:
      :CUSTOM_ID: main.Test.f'
      :CUSTOM_ID: Test.f'
      :END:

a function with a prime can be referred to as [[#main.Test.f'][f']] but f' doesn't get link'd 'f''

***** withType :: [[#base.Data.Int.Int][Int]]
      :PROPERTIES:
      :CUSTOM_ID: main.Test.withType
      :CUSTOM_ID: Test.withType
      :END:

Comment on a definition with type signature

***** withoutType :: a
      :PROPERTIES:
      :CUSTOM_ID: main.Test.withoutType
      :CUSTOM_ID: Test.withoutType
      :END:

Comment on a definition without type signature

** Visible
   :PROPERTIES:
   :CUSTOM_ID: main.Visible
   :Hackage: https://hackage.haskell.org/package/main/docs/Visible.html
   :END:

*** visible :: [[#base.Data.Int.Int][Int]] -> [[#base.Data.Int.Int][Int]]
    :PROPERTIES:
    :CUSTOM_ID: main.Visible.visible
    :CUSTOM_ID: Visible.visible
    :END: