From 09a40346d33bf9feef333e3d9a43eb0bbf6dfa69 Mon Sep 17 00:00:00 2001
From: "Patrick M. Niedzielski" <patrick@pniedzielski.net>
Date: Wed, 20 Mar 2024 05:53:44 +0000
Subject: [PATCH] Document IRIs using `rdfs:comment`

This patch reads all `rdfs:comment`s for a given subject, concatenates
them together, separated by newlines, and uses this value as the
Haddock documentation for that subject.

Not all vocabularies in this library are fully documented using
`rdfs:comment`, though, so there remain some generated subjects that
lack documentation.  This is for two reasons.  First, for those nodes
that lack any documentation at all, this patch elects to remain
faithful to the underlying vocabulary and keep these nodes
undocumented.  Second, some vocabularies, like SKOS, use their own
predicate for documentation; this patch chooses to only read the
standard `rdfs:comment`.  Additional documentation vocabularies can be
added later if required.
---
 .../Generator/VocabularyGenerator.hs          | 29 +++++++++++++++++--
 1 file changed, 27 insertions(+), 2 deletions(-)

diff --git a/src/Data/RDF/Vocabulary/Generator/VocabularyGenerator.hs b/src/Data/RDF/Vocabulary/Generator/VocabularyGenerator.hs
index 3496d4a..4286ffa 100644
--- a/src/Data/RDF/Vocabulary/Generator/VocabularyGenerator.hs
+++ b/src/Data/RDF/Vocabulary/Generator/VocabularyGenerator.hs
@@ -6,19 +6,23 @@ module Data.RDF.Vocabulary.Generator.VocabularyGenerator
   )
 where
 
+import Control.Monad (join)
 import Data.Char (isLower)
 import Data.List (nub)
 import qualified Data.Map as M
 import Data.Maybe (maybeToList)
 import Data.RDF
   ( AdjHashMap,
-    Node (UNode),
+    LValue (..),
+    Node (..),
     PrefixMappings (PrefixMappings),
     RDF,
     Rdf,
     TurtleParser (TurtleParser),
+    objectOf,
     parseFile,
     prefixMappings,
+    query,
     subjectOf,
     triplesOf,
   )
@@ -64,7 +68,11 @@ vocabulary graph =
         subject <- nub $ subjectOf <$> triplesOf graph
         iri <- maybeToList $ toIRI subject
         name <- maybeToList $ iriToName iri
-        return (name, declareIRI name iri Nothing)
+        let comment = combineComments .
+                      sequenceA .
+                      fmap (nodeToComment . objectOf) $
+                      query graph (Just subject) (Just rdfsCommentNode) Nothing
+        return (name, declareIRI name iri comment)
       (PrefixMappings prefixMappings') = prefixMappings graph
       namespaceDecls = do
         (prefix, iri) <- M.toList prefixMappings'
@@ -87,6 +95,23 @@ unodeFun = VarE $ mkName "Data.RDF.Types.unode"
 mkPrefixedNSFun :: Exp
 mkPrefixedNSFun = VarE $ mkName "Data.RDF.Namespace.mkPrefixedNS"
 
+nodeToComment :: Node -> Maybe Text
+nodeToComment (UNode uri)           = Just $ "See \\<<" <> uri <> ">\\>."
+nodeToComment (BNode _)             = Nothing
+nodeToComment (BNodeGen _)          = Nothing
+nodeToComment (LNode (PlainL l))    = Just l
+nodeToComment (LNode (PlainLL l _)) = Just l
+nodeToComment (LNode (TypedL l _))  = Just l
+
+combineComments :: Maybe [Text] -> Maybe Text
+combineComments = join . fmap combineComments'
+  where
+    combineComments' [] = Nothing
+    combineComments' comments = Just . T.intercalate "\n" $ comments
+
+rdfsCommentNode :: Node
+rdfsCommentNode = UNode "http://www.w3.org/2000/01/rdf-schema#comment"
+
 declareIRI :: Name -> Text -> Maybe Text -> Q Dec
 declareIRI name iri comment =
   let iriLiteral = LitE . StringL $ T.unpack iri