From 51469055a31ba9b85fce4977cab486a169a1ee4d Mon Sep 17 00:00:00 2001
From: Lars Wirzenius <liw@liw.fi>
Date: Fri, 1 Dec 2023 11:02:54 +0200
Subject: docs: add doc to bindings in share/common/files.yaml

Signed-off-by: Lars Wirzenius <liw@liw.fi>
Sponsored-by: author
---
 share/common/lib/files.yaml | 56 ++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 55 insertions(+), 1 deletion(-)

(limited to 'share')

diff --git a/share/common/lib/files.yaml b/share/common/lib/files.yaml
index cb39b96..8f3f932 100644
--- a/share/common/lib/files.yaml
+++ b/share/common/lib/files.yaml
@@ -10,6 +10,9 @@
       function: files_create_from_embedded
   types:
     embedded_file: file
+  doc: |
+    Create a file on disk from an embedded file in the subplot
+    document. The created file has the same name as the embedded file.
 
 - given: file {filename_on_disk} from {embedded_file}
   impl:
@@ -20,6 +23,9 @@
   types:
     filename_on_disk: path
     embedded_file: file
+  doc: |
+    Create a file on disk from an embedded file in the subplot
+    document. Set the name of the created file.
 
 - when: I write "{text}" to file {filename}
   impl:
@@ -30,6 +36,8 @@
   types:
     filename: path
     text: text
+  doc: |
+    Create a file on disk with the given content.
 
 # Manage directories (distinct from files).
 
@@ -41,6 +49,8 @@
       function: files_make_directory
   types:
     path: path
+  doc: |
+    Create a directory on disk.
 
 - when: I create directory {path}
   impl:
@@ -50,6 +60,8 @@
       function: files_make_directory
   types:
     path: path
+  doc: |
+    Create a directory on disk.
 
 - when: I remove directory {path}
   impl:
@@ -59,6 +71,8 @@
       function: files_remove_directory
   types:
     path: path
+  doc: |
+    Remove a directory on disk.
 
 - then: directory {path} exists
   impl:
@@ -68,6 +82,8 @@
       function: files_directory_exists
   types:
     path: path
+  doc: |
+    Check that a directory exists.
 
 - then: directory {path} does not exist
   impl:
@@ -77,6 +93,8 @@
       function: files_directory_does_not_exist
   types:
     path: path
+  doc: |
+    Check that a directory does not exist.
 
 - then: directory {path} is empty
   impl:
@@ -86,6 +104,8 @@
       function: files_directory_is_empty
   types:
     path: path
+  doc: |
+    Check that a directory exists and does not contain anything.
 
 - then: directory {path} is not empty
   impl:
@@ -95,6 +115,8 @@
       function: files_directory_is_not_empty
   types:
     path: path
+  doc: |
+    Check that a directory exists and contains something.
 
 # File metadata management and testing.
 
@@ -108,6 +130,8 @@
   types:
     filename: path
     mtime: text
+  doc: |
+    Create a file with specific modification time.
 
 - when: I remember metadata for file {filename}
   impl:
@@ -117,6 +141,8 @@
       function: files_remember_metadata
   types:
     filename: path
+  doc: |
+    Remember the metadata of a file.
 
 - when: I touch file {filename}
   impl:
@@ -126,6 +152,8 @@
       function: files_touch
   types:
     filename: path
+  doc: |
+    Update the modification time of a file to be current time.
 
 - then: file {filename} has same metadata as before
   impl:
@@ -135,6 +163,9 @@
       function: files_has_remembered_metadata
   types:
     filename: path
+  doc: |
+    Check that a file has the same metadata as remembered from
+    earlier.
 
 - then: file {filename} has different metadata from before
   impl:
@@ -144,6 +175,8 @@
       function: files_has_different_metadata
   types:
     filename: path
+  doc: |
+    Check that a file metadata has changed from earlier.
 
 - then: file {filename} has changed from before
   impl:
@@ -153,6 +186,8 @@
       function: files_has_different_metadata
   types:
     filename: path
+  doc: |
+    Check that file metadata has changed from before.
 
 - then: file {filename} has a very recent modification time
   impl:
@@ -162,6 +197,8 @@
       function: files_mtime_is_recent
   types:
     filename: path
+  doc: |
+    Check that file modification time is recent.
 
 - then: file {filename} has a very old modification time
   impl:
@@ -171,6 +208,8 @@
       function: files_mtime_is_ancient
   types:
     filename: path
+  doc: |
+    Check that file modification is far in the past.
 
 # Testing file existence.
 
@@ -182,6 +221,8 @@
       function: files_file_exists
   types:
     filename: path
+  doc: |
+    Check that a file exist.
 
 - then: file {filename} does not exist
   impl:
@@ -191,6 +232,8 @@
       function: files_file_does_not_exist
   types:
     filename: path
+  doc: |
+    Check that a file does not exist.
 
 - then: only files (?P<filenames>.+) exist
   impl:
@@ -199,6 +242,8 @@
     python:
       function: files_only_these_exist
   regex: true
+  doc: |
+    Check that the test directory only contains specific files.
 
 # Tests on file content.
 
@@ -211,6 +256,8 @@
   types:
     filename: path
     data: text
+  doc: |
+    Check that a file contains a string.
 
 - then: file {filename} doesn't contain "{data}"
   impl:
@@ -221,6 +268,8 @@
   types:
     filename: path
     data: text
+  doc: |
+    Check that a file does not contain a string.
 
 - then: file {filename} matches regex /{regex}/
   impl:
@@ -231,6 +280,8 @@
   types:
     filename: path
     regex: text
+  doc: |
+    Check that file content matches a regular expression.
 
 - then: file {filename} matches regex "{regex}"
   impl:
@@ -241,6 +292,8 @@
   types:
     filename: path
     regex: text
+  doc: |
+    Check that file content matches a regular expression.
 
 - then: files {filename1} and {filename2} match
   impl:
@@ -251,4 +304,5 @@
   types:
     filename1: path
     filename2: path
-
+  doc: |
+    Check that two files have the same content.
-- 
cgit v1.2.1