Extending scan API documentation a bit

Signed-off-by: Christian Parpart <[email protected]>

Author: christianparpart

src/libunicode/scan.h

@@ -56,8 +56,22 @@ class grapheme_cluster_receiver
   public:
     virtual ~grapheme_cluster_receiver() = default;
 
+    // Event handler for US-ASCII sequences received.
+    //
+    // @param codepoints    US-ASCII codepoints
     virtual void receiveAsciiSequence(std::string_view codepoints) noexcept = 0;
+
+    // Event handler for grapheme clusters received.
+    //
+    // @param codepoints    UTF-8 encoded grapheme cluster
+    // @param columnCount   number of columns this grapheme cluster spans
     virtual void receiveGraphemeCluster(std::string_view codepoints, size_t columnCount) noexcept = 0;
+
+    // Event handler for invalid UTF-8 byte sequence received.
+    //
+    // @param sequence    invalid UTF-8 byte sequence
+    //
+    // This is usually called when the input sequence contains an invalid UTF-8 byte sequence.
     virtual void receiveInvalidGraphemeCluster(std::string_view sequence) noexcept = 0;
 };
 
@@ -78,7 +92,22 @@ class null_receiver final: public grapheme_cluster_receiver
 
 namespace detail
 {
+    // Scans ASCII text for grapheme clusters.
+    //
+    // @param text            UTF-8 text to be (resumed) to be scanned
+    // @param maxColumnCount  number of columns to be scanned at most
+    //
+    // @return Number of US-ASCII text columns scanned.
     size_t scan_for_text_ascii(std::string_view text, size_t maxColumnCount) noexcept;
+
+    // Scans non-ASCII text for grapheme clusters.
+    //
+    // @param state           scan state to be used
+    // @param text            UTF-8 text to be (resumed) to be scanned
+    // @param maxColumnCount  number of columns to be scanned at most
+    // @param receiver        event listener to be informed about
+    //
+    // @return scanned textual result.
     scan_result scan_for_text_nonascii(scan_state& state,
                                        std::string_view text,
                                        size_t maxColumnCount,
@@ -104,6 +133,14 @@ namespace detail
 ///         but not incomplete codepoints at the end.
 scan_result scan_text(scan_state& state, std::string_view text, size_t maxColumnCount) noexcept;
 
+/// Scans the text until the next control character,
+/// or the maximum number of columns have been processed.
+///
+/// @param state
+/// @param text            UTF-8 text to be (resumed) to be scanned
+/// @param maxColumnCount  number of columns to be scanned at most
+/// @param receiver        event listener to be informed about
+///                        new grapheme clusters etc
 scan_result scan_text(scan_state& state,
                       std::string_view text,
                       size_t maxColumnCount,