Add documentation for the Clang.File module. #23

chetant · Apr 22, 2014 · 7fb0288 · 7fb0288
1 parent afa445c
commit 7fb0288
Show file tree

Hide file tree

Showing 3 changed files with 54 additions and 32 deletions.
diff --git a/src/Clang.hs b/src/Clang.hs
@@ -75,7 +75,6 @@ module Clang (
 , FFI.Diagnostic
 , FFI.DiagnosticSet
 , FFI.File
-, FFI.FileUniqueId
 , FFI.Remapping
 , FFI.SourceLocation
 , FFI.SourceRange

diff --git a/src/Clang/File.hs b/src/Clang/File.hs
@@ -1,13 +1,24 @@
 {-# LANGUAGE ConstraintKinds #-}
 {-# LANGUAGE FlexibleContexts #-}
 
+-- | Functions for manipulating 'FFI.File's, which represent
+-- references to files in the libclang AST.
+--
+-- This module is intended to be imported qualified.
 module Clang.File
-( getName
-, getPOSIXTime
-, getUTCTime
-, getFile
-, getFileUniqueId
-, isFileMultipleIncludeGuarded
+(
+-- * Creating files
+  createFromPath
+
+-- * File properties
+, getName
+, isMultipleIncludeGuarded
+, getMTime
+, getPosixMTime
+
+-- * Unique IDs
+, getUniqueId
+, FFI.UniqueId
 ) where
 
 import Control.Monad.IO.Class
@@ -18,21 +29,32 @@ import Data.Time.Clock (UTCTime)
 import qualified Clang.Internal.FFI as FFI
 import Clang.Internal.Monad
 
+-- | Create a new 'FFI.File' value from the provided path.
+createFromPath :: ClangBase m => FFI.TranslationUnit s' -> FilePath -> ClangT s m (FFI.File s)
+createFromPath t f = liftIO $ FFI.getFile mkProxy t f
+
+-- | Retrieve the filename of the given file.
 getName :: ClangBase m => FFI.File s' -> ClangT s m (FFI.ClangString s)
 getName = FFI.getFileName
 
-getPOSIXTime :: ClangBase m => FFI.File s' -> ClangT s m POSIXTime
-getPOSIXTime f = liftIO $ realToFrac <$> FFI.getFileTime f
-
-getUTCTime :: ClangBase m => FFI.File s' -> ClangT s m UTCTime
-getUTCTime f = liftIO $ posixSecondsToUTCTime . realToFrac <$> FFI.getFileTime f
-
-getFile :: ClangBase m => FFI.TranslationUnit s' -> FilePath -> ClangT s m (FFI.File s)
-getFile t f = liftIO $ FFI.getFile mkProxy t f
-
-getFileUniqueId :: ClangBase m => FFI.File s' -> ClangT s m (Maybe FFI.FileUniqueId)
-getFileUniqueId f = liftIO $ FFI.getFileUniqueID f
-
-isFileMultipleIncludeGuarded :: ClangBase m => FFI.TranslationUnit s' -> FFI.File s''
-                             -> ClangT s m Bool
-isFileMultipleIncludeGuarded t f = liftIO $ FFI.isFileMultipleIncludeGuarded t f
+-- | Determines whether the given file is guarded against multiple
+-- inclusions, either with the conventional '#ifdef' / '#define' / '#endif'
+-- macro guards or with '#pragma once'.
+isMultipleIncludeGuarded :: ClangBase m => FFI.TranslationUnit s' -> FFI.File s''
+                         -> ClangT s m Bool
+isMultipleIncludeGuarded t f = liftIO $ FFI.isFileMultipleIncludeGuarded t f
+
+-- | Returns the last modification time of the given file, represented
+-- as a 'UTCTime'.
+getMTime :: ClangBase m => FFI.File s' -> ClangT s m UTCTime
+getMTime f = liftIO $ posixSecondsToUTCTime . realToFrac <$> FFI.getFileTime f
+
+-- | Returns the last modification time of the given file, represented
+-- as a 'POSIXTime'.
+getPosixMTime :: ClangBase m => FFI.File s' -> ClangT s m POSIXTime
+getPosixMTime f = liftIO $ realToFrac <$> FFI.getFileTime f
+
+-- | Retrieves a unique ID for the given file. If no unique ID can be
+-- generated, returns 'Nothing'.
+getUniqueId :: ClangBase m => FFI.File s' -> ClangT s m (Maybe FFI.UniqueId)
+getUniqueId f = liftIO $ FFI.getFileUniqueID f
diff --git a/src/Clang/Internal/FFI.gc b/src/Clang/Internal/FFI.gc
@@ -35,7 +35,7 @@ module Clang.Internal.FFI
 , File(..)
 , getFileName
 , getFileTime
-, FileUniqueId(..)
+, UniqueId(..)
 , getFileUniqueID
 , isFileMultipleIncludeGuarded
 , getFile
@@ -755,24 +755,25 @@ foreign import ccall unsafe "clang-c/Index.h clang_getFileTime" clang_getFileTim
 getFileTime :: File s -> IO CTime
 getFileTime (File ptr) = clang_getFileTime ptr
 
-data FileUniqueId = FileUniqueId !Word64 !Word64 !Word64
+-- | A unique identifier that can be used to distinguish 'File's.
+data UniqueId = UniqueId !Word64 !Word64 !Word64
   deriving (Eq, Ord, Show)
 
-instance Hashable FileUniqueId where
-    hashWithSalt salt (FileUniqueId a b c) = (`hashWithSalt` a)
-                                           . (`hashWithSalt` b)
-                                           . (`hashWithSalt` c)
-                                           $ salt
+instance Hashable UniqueId where
+    hashWithSalt salt (UniqueId a b c) = (`hashWithSalt` a)
+                                       . (`hashWithSalt` b)
+                                       . (`hashWithSalt` c)
+                                       $ salt
     {-# INLINE hashWithSalt #-}
 
-maybeFileUniqueID :: (Int, Word64, Word64, Word64) -> Maybe FileUniqueId
+maybeFileUniqueID :: (Int, Word64, Word64, Word64) -> Maybe UniqueId
 maybeFileUniqueID (v, d1, d2, d3) | v /= 0    = Nothing
-                                  | otherwise = Just $ FileUniqueId d1 d2 d3
+                                  | otherwise = Just $ UniqueId d1 d2 d3
 
 %dis maybe_fileUniqueID v d1 d2 d3 = <id/maybeFileUniqueID> (int v) (word64 d1) (word64 d2) (word64 d3)
 
 -- int clang_getFileUniqueID(CXFile file, CXFileUniqueID *outID);
-%fun clang_getFileUniqueID :: File s -> IO (Maybe FileUniqueId)
+%fun clang_getFileUniqueID :: File s -> IO (Maybe UniqueId)
 %call (file f)
 %code CXFileUniqueID uid;
 %     int r = clang_getFileUniqueID(f, &uid);