update pl.file docs (remove and replace with references)

Since this module has outdated docs, the contents is removed and
replaced with references to the original functions as to reduce
documentation maintenance.

1 files changed, 15 insertions, 22 deletions

diff --git a/lua/pl/file.lua b/lua/pl/file.lua
index 572d7fc..b8058c4 100644
--- a/lua/pl/file.lua
+++ b/lua/pl/file.lua
@@ -1,5 +1,8 @@
 --- File manipulation functions: reading, writing, moving and copying.
 --
+-- This module wraps a number of functions from other modules into a
+-- file related module for convenience.
+--
 -- Dependencies: `pl.utils`, `pl.dir`, `pl.path`
 -- @module pl.file
 local os = os
@@ -7,56 +10,46 @@ local utils = require 'pl.utils'
 local dir = require 'pl.dir'
 local path = require 'pl.path'
 
---[[
-module ('pl.file',utils._module)
-]]
 local file = {}
 
---- return the contents of a file as a string
+--- return the contents of a file as a string.
+-- This function is a copy of `utils.readfile`.
 -- @function file.read
--- @string filename The file path
--- @return file contents
 file.read = utils.readfile
 
---- write a string to a file
+--- write a string to a file.
+-- This function is a copy of `utils.writefile`.
 -- @function file.write
--- @string filename The file path
--- @string str The string
 file.write = utils.writefile
 
 --- copy a file.
+-- This function is a copy of `dir.copyfile`.
 -- @function file.copy
--- @string src source file
--- @string dest destination file
--- @bool flag true if you want to force the copy (default)
--- @return true if operation succeeded
 file.copy = dir.copyfile
 
 --- move a file.
+-- This function is a copy of `dir.movefile`.
 -- @function file.move
--- @string src source file
--- @string dest destination file
--- @return true if operation succeeded, else false and the reason for the error.
 file.move = dir.movefile
 
 --- Return the time of last access as the number of seconds since the epoch.
+-- This function is a copy of `path.getatime`.
 -- @function file.access_time
--- @string path A file path
 file.access_time = path.getatime
 
 ---Return when the file was created.
+-- This function is a copy of `path.getctime`.
 -- @function file.creation_time
--- @string path A file path
 file.creation_time = path.getctime
 
---- Return the time of last modification
+--- Return the time of last modification.
+-- This function is a copy of `path.getmtime`.
 -- @function file.modified_time
--- @string path A file path
 file.modified_time = path.getmtime
 
---- Delete a file
+--- Delete a file.
+-- This function is a copy of `os.remove`.
 -- @function file.delete
--- @string path A file path
 file.delete = os.remove
 
 return file