From 33175ad9ba44bd32bf482e18ca9d64c431000c5e Mon Sep 17 00:00:00 2001
From: Harry Garrood <harry@garrood.me>
Date: Sun, 9 Jul 2017 22:40:05 +0100
Subject: [PATCH 1/2] Fix child declarations order in HTML docs

Child declarations - that is, data constructors, type class members, and
instances - were appearing in the reverse order because of how the
`partitionChildren` function works.

This fixes https://github.com/purescript/pursuit/issues/125.
---
 src/Language/PureScript/Docs/AsHtml.hs | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/Language/PureScript/Docs/AsHtml.hs b/src/Language/PureScript/Docs/AsHtml.hs
index cc1568d35f..f7f3ba1e03 100644
--- a/src/Language/PureScript/Docs/AsHtml.hs
+++ b/src/Language/PureScript/Docs/AsHtml.hs
@@ -294,10 +294,13 @@ withClass className content = H.span ! A.class_ (fromString className) $ content
 partitionChildren ::
   [ChildDeclaration] ->
   ([ChildDeclaration], [ChildDeclaration], [ChildDeclaration])
-partitionChildren = foldl go ([], [], [])
+partitionChildren =
+  reverseAll . foldl go ([], [], [])
   where
   go (instances, dctors, members) rcd =
     case cdeclInfo rcd of
       ChildInstance _ _      -> (rcd : instances, dctors, members)
       ChildDataConstructor _ -> (instances, rcd : dctors, members)
       ChildTypeClassMember _ -> (instances, dctors, rcd : members)
+
+  reverseAll (xs, ys, zs) = (reverse xs, reverse ys, reverse zs)

From 431ef3d4a795cc174940ef0931b4cb02f865913f Mon Sep 17 00:00:00 2001
From: Harry Garrood <harry@garrood.me>
Date: Sun, 9 Jul 2017 23:01:17 +0100
Subject: [PATCH 2/2] Test that order of child declarations is preserved

This doesn't fully test what we want it to, as it is still possible to
accidentally reverse the list during HTML rendering. However that's not
too difficult to verify manually (as I have just done).
---
 examples/docs/src/ChildDeclOrder.purs | 27 +++++++++++++++++++++++++++
 tests/TestDocs.hs                     | 14 +++++++++-----
 2 files changed, 36 insertions(+), 5 deletions(-)
 create mode 100644 examples/docs/src/ChildDeclOrder.purs

diff --git a/examples/docs/src/ChildDeclOrder.purs b/examples/docs/src/ChildDeclOrder.purs
new file mode 100644
index 0000000000..7f677856e7
--- /dev/null
+++ b/examples/docs/src/ChildDeclOrder.purs
@@ -0,0 +1,27 @@
+-- Tests should ensure that, in the docs:
+--  - First should come before Second
+--  - foo1 should be listed before foo2
+--  - the instances should be listed in the same order as this source file
+module ChildDeclOrder where
+
+data Two
+  = First
+  | Second
+
+class Show a where
+  show :: a -> String
+
+class Foo a where
+  foo1 :: a
+  foo2 :: a
+
+instance showTwo :: Show Two where
+  show _  = ""
+
+instance fooTwo :: Foo Two where
+  foo1 = First
+  foo2 = Second
+
+instance fooInt :: Foo Int where
+  foo1 = 1
+  foo2 = 2
diff --git a/tests/TestDocs.hs b/tests/TestDocs.hs
index 0237bfee8f..d3dbbdbd35 100644
--- a/tests/TestDocs.hs
+++ b/tests/TestDocs.hs
@@ -13,7 +13,6 @@ import Control.Arrow (first)
 import Control.Monad.IO.Class (liftIO)
 
 import Data.Foldable
-import Data.List ((\\))
 import Data.Maybe (fromMaybe)
 import Data.Monoid
 import Data.Text (Text)
@@ -99,7 +98,7 @@ instance Show (ShowFn a) where
 data AssertionFailure
   -- | A declaration was not documented, but should have been
   = NotDocumented P.ModuleName Text
-  -- | A child declaration was not documented, but should have been
+  -- | The expected list of child declarations did not match the actual list
   | ChildrenNotDocumented P.ModuleName Text [Text]
   -- | A declaration was documented, but should not have been
   | Documented P.ModuleName Text
@@ -152,9 +151,9 @@ runAssertion assertion linksCtx Docs.Module{..} =
         Nothing ->
           Fail (NotDocumented mn decl)
         Just actualChildren ->
-          case children \\ actualChildren of
-            [] -> Pass
-            cs -> Fail (ChildrenNotDocumented mn decl cs)
+          if children == actualChildren
+            then Pass
+            else Fail (ChildrenNotDocumented mn decl actualChildren)
 
     ShouldNotBeDocumented mn decl ->
       case findChildren decl (declarationsFor mn) of
@@ -406,6 +405,11 @@ testCases =
   , ("Desugar",
       [ ValueShouldHaveTypeSignature (n "Desugar") "test" (renderedType "forall a b. X (a -> b) a -> b")
       ])
+
+  , ("ChildDeclOrder",
+      [ ShouldBeDocumented (n "ChildDeclOrder") "Two" ["First", "Second", "showTwo", "fooTwo"]
+      , ShouldBeDocumented (n "ChildDeclOrder") "Foo" ["foo1", "foo2", "fooTwo", "fooInt"]
+      ])
   ]
 
   where