docs(base): fix and improve docs for self:with_suffix

Release-As: 2.1.0

Author: pysan3

lua/pathlib/base.lua

@@ -298,6 +298,16 @@ function Path:with_basename(name)
 end
 
 ---Return the group name of the file GID. Same as `str(self) minus self:modify(":r")`.
+---
+--->>> Path("folder/foo.txt"):suffix()
+---"foo"
+--->>> Path("folder/no-extension"):suffix()
+---""
+--->>> Path("folder/.bashrc"):suffix()
+---".bashrc"
+--->>> Path("folder/archive.tar.gz"):suffix()
+---"archive.tar"
+---
 ---@return string # extension of path including the dot (`.`): `.py`, `.lua` etc
 function Path:suffix()
   local s, counter = self:basename():gsub("^.*(%.[^.]+)$", "%1", 1)
@@ -306,25 +316,27 @@ end
 
 ---Return new object with new suffix.
 ---
---->>> Path("./folder/foo.txt"):with_suffix("png")
+--->>> Path("./folder/foo.txt"):with_suffix(".png")
 ---Path("./folder/foo.png")
 ---
+---@see PathlibPath.add_suffix as well
 ---@param suffix string # New suffix
 function Path:with_suffix(suffix)
   local name = self:stem() .. suffix
   return self:with_basename(name)
 end
 
 ---Append given `suffix` to path, if suffix is not as same as given.
+---@see PathlibPath.with_suffix as well
 ---
---->>> Path("./folder/foo.tar"):add_suffix("gz")
+--->>> Path("./folder/foo.tar"):add_suffix(".gz")
 ---Path("./folder/foo.tar.gz")
 ---
---->>> Path("./folder/foo.txt.bak"):add_suffix("bak")
+--->>> Path("./folder/foo.txt.bak"):add_suffix(".bak")
 ---Path("./folder/foo.txt.bak") -- is already ".bak", so no change applied
 ---
 ---@param suffix string # Append this suffix to path, if suffix is not already equal.
----@param force boolean|nil # If true, always append given suffix. Result will become `foo.txt.bak.bak` in above expample.
+---@param force boolean|nil # If true, always append given suffix. Result will be `foo.txt.bak.bak` in above expample.
 function Path:add_suffix(suffix, force)
   local basename = self:basename()
   if force or basename:sub(-suffix:len()) ~= suffix then