documented windows filters (#78876)

* documented windows filters

Co-authored-by: Felix Fontein <felix@fontein.de>
Co-authored-by: Sandra McCann <samccann@redhat.com>

lib/ansible/plugins/filter/win_basename.yml

@@ -0,0 +1,24 @@
+DOCUMENTATION:
+  name: win_basename
+  author: ansible core team
+  version_added: "2.0"
+  short_description: Get a Windows path's base name
+  description:
+    - Returns the last name component of a Windows path, what is left in the string that is not 'win_dirname'.
+  options:
+    _input:
+      description: A Windows path.
+      type: str
+      required: true
+  seealso:
+    - plugin_type: filter
+      plugin: ansible.builtin.win_dirname
+EXAMPLES: |
+
+  # To get the last name of a file Windows path, like 'foo.txt' out of 'C:\Users\asdf\foo.txt'
+  {{ mypath | win_basename }}
+
+RETURN:
+  _value:
+    description: The base name from the Windows path provided.
+    type: str

lib/ansible/plugins/filter/win_dirname.yml

@@ -0,0 +1,24 @@
+DOCUMENTATION:
+  name: win_dirname
+  author: ansible core team
+  version_added: "2.0"
+  short_description: Get a Windows path's directory
+  description:
+    - Returns the directory component of a Windows path, what is left in the string that is not 'win_basename'.
+  options:
+    _input:
+      description: A Windows path.
+      type: str
+      required: true
+  seealso:
+    - plugin_type: filter
+      plugin: ansible.builtin.win_basename
+EXAMPLES: |
+
+  # To get the last name of a file Windows path, like 'C:\users\asdf' out of 'C:\Users\asdf\foo.txt'
+  {{ mypath | win_dirname }}
+
+RETURN:
+  _value:
+    description: The directory from the Windows path provided.
+    type: str

lib/ansible/plugins/filter/win_splitdrive.yml

@@ -0,0 +1,29 @@
+DOCUMENTATION:
+  name: win_splitdrive
+  author: ansible core team
+  version_added: "2.0"
+  short_description: Split a Windows path by the drive letter
+  description:
+    - Returns a list with the first component being the drive letter and the second, the rest of the path.
+  options:
+    _input:
+      description: A Windows path.
+      type: str
+      required: true
+
+EXAMPLES: |
+
+  # To get the last name of a file Windows path, like ['C', '\Users\asdf\foo.txt'] out of 'C:\Users\asdf\foo.txt'
+  {{ mypath | win_splitdrive }}
+
+  # just the drive letter
+  {{ mypath | win_splitdrive | first }}
+
+  # path w/o drive letter
+  {{ mypath | win_splitdrive | last }}
+
+RETURN:
+  _value:
+    description: List in which the first element is the drive letter and the second the rest of the path.
+    type: list
+    elements: str