From 861ca52a1cd2bda9099098ddb0a1c2dfcbb57c3a Mon Sep 17 00:00:00 2001
From: Paul Ferrand <paul@ferrand.cc>
Date: Wed, 18 Dec 2019 11:19:10 +0100
Subject: [PATCH] Docs on the parsing functions

---
 src/sfizz/SfzHelpers.h | 58 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/src/sfizz/SfzHelpers.h b/src/sfizz/SfzHelpers.h
index bf8c9083..b847d757 100644
--- a/src/sfizz/SfzHelpers.h
+++ b/src/sfizz/SfzHelpers.h
@@ -126,9 +126,67 @@ inline float ccSwitchedValue(const SfzCCArray& ccValues, const absl::optional<CC
  */
 absl::optional<uint8_t> readNoteValue(const absl::string_view& value);
 
+/**
+ * @brief From a source view, find the next sfz header and its members and
+ *          return them, while updating the source by removing this header
+ *          and members from the beginning. The function "consumes" the
+ *          header and its members from the source if found.
+ * 
+ * No check is made to see if the header is "valid" in the sfz sense.
+ * The output parameters are set only if the method returns true.
+ * 
+ * @param source A source view; can be updated and shortened
+ * @param header An output view on the header, without the <>
+ * @param members An output view on the members, untrimmed
+ * @return true if a header was found
+ * @return false otherwise
+ */
 bool findHeader(absl::string_view& source, absl::string_view& header, absl::string_view& members);
+/**
+ * @brief From a source view, find the next sfz member opcode and its value.
+ *          Return them while updating the source by removing this opcode
+ *          and value from the beginning. The function "consumes" the
+ *          opcode from the source if one is found.
+ * 
+ * No check is made to see if the opcode is "valid" in the sfz sense.
+ * The output parameters are set only if the method returns true.
+ * 
+ * @param source A source view; can be updated and shortened
+ * @param opcode An output view on the opcode name
+ * @param value An output view on the opcode value
+ * @return true if an opcode was found
+ * @return false 
+ */
 bool findOpcode(absl::string_view& source, absl::string_view& opcode, absl::string_view& value);
+
+/**
+ * @brief Find an SFZ #define statement on a line and return the variable and value as views.
+ * 
+ * This function assums that there is a single define per line and that the variable and value
+ * are separated by whitespace.
+ * The output parameters are set only if the method returns true.
+ * 
+ * @param line The source line
+ * @param variable An output view on the define variable
+ * @param value An output view on the define value
+ * @return true If a define was found
+ * @return false 
+ */
 bool findDefine(absl::string_view line, absl::string_view& variable, absl::string_view& value);
+
+/**
+ * @brief Find an SFZ #include statement on a line and return included path.
+ * 
+ * This function assums that there is a single include per line and that the
+ * include path is within quotes.
+ * The output parameter is set only if the method returns true.
+ * 
+ * @param line The source line
+ * @param path The path, if found
+ * @return true If an include was found
+ * @return false 
+ */
 bool findInclude(absl::string_view line, std::string& path);
+
 } // namespace sfz