[commit: packages/filepath] master: Improve the docs for stripExtension (a38cc73)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/filepath

On branch  : master
Link       : http://git.haskell.org/packages/filepath.git/commitdiff/a38cc733674497875ad76240c24a17ec1a0d568b

>---------------------------------------------------------------

commit a38cc733674497875ad76240c24a17ec1a0d568b
Author: Neil Mitchell <ndmitchell at gmail.com>
Date:   Tue Dec 22 14:34:19 2015 +0000

    Improve the docs for stripExtension


>---------------------------------------------------------------

a38cc733674497875ad76240c24a17ec1a0d568b
 System/FilePath/Internal.hs | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

diff --git a/System/FilePath/Internal.hs b/System/FilePath/Internal.hs
index 3b7fa48..df4b39c 100644
--- a/System/FilePath/Internal.hs
+++ b/System/FilePath/Internal.hs
@@ -312,14 +312,12 @@ hasExtension :: FilePath -> Bool
 hasExtension = any isExtSeparator . takeFileName
 
 
--- | Drop the given extension from a FilePath, and the \".\" preceding it.
+-- | Drop the given extension from a FilePath, and the @\".\"@ preceding it.
+--   Returns 'Nothing' if the FilePath does not have the given extension, or
+--   'Just' and the part before the extension if it does.
 --
--- It returns Nothing if the FilePath does not have the extension given, or
--- Just the part before the extension, if it does.
---
--- It is safer to use this function than System.FilePath.dropExtensions,
--- because FilePath might be something like 'file.name.ext1.ext2', where we
--- want to only drop the 'ext1.ext2' part, but keep the full 'file.name' part.
+--   This function can be more predictable than 'dropExtensions', especially if the filename
+--   might itself contain @.@ characters.
 --
 -- > stripExtension "hs.o" "foo.x.hs.o" == Just "foo.x"
 -- > stripExtension "hi.o" "foo.x.hs.o" == Nothing