More documentation work

gershnik · Jan 18, 2024 · 330acc3 · 330acc3
1 parent 418edcd
commit 330acc3
Show file tree

Hide file tree

Showing 6 changed files with 56 additions and 33 deletions.
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -1,3 +1,20 @@
 {
-    "C_Cpp.autoAddFileAssociations": false
+    "C_Cpp.autoAddFileAssociations": false,
+    "C_Cpp.default.cppStandard": "gnu++20",
+    "C_Cpp.default.intelliSenseMode": "macos-clang-x86",
+    "spellright.language": [
+        "en"
+    ],
+    "spellright.documentTypes": [
+        "markdown",
+        "latex",
+        "plaintext",
+        "cpp",
+        "objective-cpp"
+    ],
+    "spellright.parserByClass": {
+        "objective-cpp": {
+            "parser": "code"
+        }
+    },
 }
diff --git a/.vscode/spellright.dict b/.vscode/spellright.dict
@@ -2,4 +2,6 @@ awaitable
 awaitables
 Promisify
 callables
-wrappable
+wrappable
+transcodings
+awaiter
diff --git a/include/objc-helpers/BlockUtil.h b/include/objc-helpers/BlockUtil.h
@@ -46,7 +46,7 @@
    expensive to copy - oh well...
  * Because of the above you cannot have move-only thinks in your block. Forget about using `std::unique_ptr` for example.
 
- Theis  header gives you an ability to solve all of these problems.
+ This  header gives you an ability to solve all of these problems.
 
  It provides two functions: `makeBlock` and `makeMutableBlock` that take any C++ callable as an input and return an object
  that is implicitly convertible to a block and can be passed to any block-taking API. They (or rather the object they return)
@@ -132,7 +132,7 @@ namespace BlockUtil
          * Usually you don't want to create instances of this class directly. Instead use `makeBlock` and
          * `makeMutableBlock` factory functions that will do all the necessary deductions and checks for you.
          *
-         * This class is NOT the same as block pointer like void (^)(). It IS a bloack and is more akin to an std::function
+         * This class is NOT the same as block pointer like void (^)(). It IS a block and is more akin to an std::function
          * (only without any dynamic memory allocations). It can be copied by value, stored etc. and,
          * when needed, **converted to a block pointer**
          *

diff --git a/include/objc-helpers/CoDispatch.h b/include/objc-helpers/CoDispatch.h
@@ -186,9 +186,9 @@ inline namespace CO_DISPATCH_NS {
         /**
          We need a way to transfer return values from coroutines to clients.
          This is a generic "holder of value" that can handle anything that can be returned by a function.
-         It can, potentialy also store an exception depending on E template parameter.
+         It can, potentially also store an exception depending on E template parameter.
          If the stored type is not `void` it also has a "not set" state used by generators to distinguish
-         yield from return and corotines to trap potential logic errors in our code.
+         yield from return and coroutines to trap potential logic errors in our code.
          */
         template<class T, SupportsExceptions E>
         class ValueCarrier {
@@ -339,7 +339,7 @@ inline namespace CO_DISPATCH_NS {
          machine that tracks client and server behavior to avoid locking.
         
          @tparam Derived the derived class for CRTP
-         @tparam DelayedValue type of ValueCarrier to store asynchrnous result
+         @tparam DelayedValue type of ValueCarrier to store asynchronous result
          */
         template<class Derived, class DelayedValue>
         class BasicPromise {
@@ -507,7 +507,7 @@ inline namespace CO_DISPATCH_NS {
         private:
             //This little trick allows us to detect if current queue is the same as the argument
             //Since Apple doesn't allow us to ask "what is the current queue" this appears to be
-            //the only way to optmize unnecessary dispatches.
+            //the only way to optimize unnecessary dispatches.
             //Setting the key is probably not cheap but likely much cheaper than suspending and
             //scheduling dispatch when none is needed.
             auto isCurrentQueue(dispatch_queue_t __nonnull queue) const {
@@ -599,7 +599,7 @@ inline namespace CO_DISPATCH_NS {
                     std::atomic_thread_fence(std::memory_order_acquire);
                     //remember, refcounting is for server (Promise) only!
                     //it is safe to cast in this case because the object is non const to begin with
-                    //and destruction is outside of constness purview
+                    //and destruction is outside of const-ness purview
                     auto h = const_cast<State *>(this)->serverComplete();
                     h.resume();
                 }
@@ -652,7 +652,7 @@ inline namespace CO_DISPATCH_NS {
             {}
 
             //These methods need to be const because promise captured in blocks will be const.
-            //Which means m_sharedState needs ot be mutable. Sigh.
+            //Which means m_sharedState needs to be mutable. Sigh.
 
             template<class... Args>
             requires(DelayedValue::template IsEmplaceableFrom<Args...>)
@@ -776,7 +776,7 @@ inline namespace CO_DISPATCH_NS {
     /**
      @function
      Converts a call with an asynchronous callback to an awaitable call
-     @param func a callable you suppliy that will eventually cause the promise passed to it to be fullfilled in some callback
+     @param func a callable you supply that will eventually cause the promise passed to it to be fulfilled in some callback
      */
     template<class Ret, SupportsExceptions E, class Func>
     requires(std::is_invocable_r_v<void, Func, typename DispatchAwaitable<Ret, E>::Promise>)
@@ -790,7 +790,7 @@ inline namespace CO_DISPATCH_NS {
      
      This overload uses default value for SupportsExceptions setting. If exceptions are enabled in compilation it supports them
      otherwise no.
-     @param func a callable you suppliy that will eventually cause the promise passed to it to be fullfilled in some callback
+     @param func a callable you supply that will eventually cause the promise passed to it to be fulfilled in some callback
      */
     template<class Ret, class Func>
     requires(std::is_invocable_r_v<void, Func, typename DispatchAwaitable<Ret, CO_DISPATCH_DEFAULT_SE>::Promise>)
@@ -1068,7 +1068,7 @@ inline namespace CO_DISPATCH_NS {
      @function
      `co_await`ing this will resume the coroutine on a given queue optionally on or after a given time
      
-     If you pass your qurrent queue and non default `when` this is equivalent to an asyncrounous sleep
+     If you pass your current queue and non default `when` this is equivalent to an asynchronous sleep
      until `when` - now.
      */
     inline auto resumeOn(dispatch_queue_t __nonnull queue, dispatch_time_t when = DISPATCH_TIME_NOW) noexcept {
@@ -1100,7 +1100,7 @@ inline namespace CO_DISPATCH_NS {
      @function
      `co_await`ing this will resume a coroutine on the main queue optionally on or after a given time
      
-     If you are already on the main queue and pass non default  `when` this is equivalent to an asyncrounous sleep
+     If you are already on the main queue and pass non default  `when` this is equivalent to an asynchronous sleep
      until `when` - now.
      */
     inline auto resumeOnMainQueue(dispatch_time_t when = DISPATCH_TIME_NOW) noexcept {
@@ -1143,7 +1143,7 @@ inline namespace CO_DISPATCH_NS {
      Coroutine version of `dispatch_io_read`
      
      Unlike `dispatch_io_read` the progressHandler parameter is optional and is only needed if you
-     want to minitor the operation progress. The final result is returned as coroutine result.
+     want to monitor the operation progress. The final result is returned as coroutine result.
      @return DispatchIOResult object with operation result
      */
     inline auto co_dispatch_io_read(dispatch_io_t __nonnull channel, off_t offset, size_t length, dispatch_queue_t __nonnull queue, dispatch_io_handler_t __nullable progressHandler = nullptr) {
@@ -1176,7 +1176,7 @@ inline namespace CO_DISPATCH_NS {
      Coroutine version of `dispatch_io_write`
      
      Unlike `dispatch_io_write` the progressHandler parameter is optional and is only needed if you
-     want to minitor the operation progress. The final result is returned as coroutine result.
+     want to monitor the operation progress. The final result is returned as coroutine result.
      
      @return DispatchIOResult object with operation result
      */

diff --git a/include/objc-helpers/NSStringUtil.h b/include/objc-helpers/NSStringUtil.h
@@ -371,12 +371,12 @@ class NSStringCharAccess
 /**
  Converts CFStringRef to `std::basic_string<Char>`
  
- @tparam Char character type of the resulatant std::basic_string
+ @tparam Char character type of the resultant std::basic_string
  @param str string to convert. If nullptr an empty string is returned
  @param start start index. If less than 0 assumed to be 0. If greater than length of the string an empty string is returned.
  @param length number of source characters to convert. If less than 0 or start + length exceeds the length of the string assumed "to the end of string".
  
- Convertions to char16_t are exact and never fail. Conversions to other character types are transcodings and can fail if source string contains invalid UTF-16
+ Conversions to char16_t are exact and never fail. Conversions to other character types are transcodings and can fail if source string contains invalid UTF-16
  sequences. In such cases an empty string is returned. Encodings of char and wchar_t are UTF-8 and UTF-32 respectively.
  */
 template<CharTypeConvertibleWithNSString Char>
@@ -416,12 +416,12 @@ auto makeStdString(CFStringRef __nullable str, CFIndex start = 0, CFIndex length
 /**
  Converts NSString to `std::basic_string<Char>`
  
- @tparam Char character type of the resulatant std::basic_string
+ @tparam Char character type of the resultant std::basic_string
  @param str string to convert. If nil an empty string is returned
  @param location start index. If greater than length of the string an empty string is returned.
  @param length number of source characters to convert. If start + length exceeds the length of the string assumed "to the end of string".
  
- Convertions to char16_t are exact and never fail. Conversions to other character types are transcodings and can fail if source string contains invalid UTF-16
+ Conversions to char16_t are exact and never fail. Conversions to other character types are transcodings and can fail if source string contains invalid UTF-16
  sequences. In such cases an empty string is returned. Encodings of char and wchar_t are UTF-8 and UTF-32 respectively.
  */
 template<CharTypeConvertibleWithNSString Char>
@@ -434,11 +434,11 @@ inline auto makeStdString(NSString * __nullable str, NSUInteger location = 0, NS
 /**
  Converts a range denoted by a pair of  NSStringCharAccess::const_iterator to `std::basic_string<Char>`
  
- @tparam Char character type of the resulatant std::basic_string
+ @tparam Char character type of the resultant std::basic_string
  
- If iterators do not form a valid substring of some NSString the behavior is undefined. If first and alst are both uninitialized iterators the result is an empty string.
+ If iterators do not form a valid substring of some NSString the behavior is undefined. If first and last are both uninitialized iterators the result is an empty string.
  
- Convertions to char16_t are exact and never fail. Conversions to other character types are transcodings and can fail if source string contains invalid UTF-16
+ Conversions to char16_t are exact and never fail. Conversions to other character types are transcodings and can fail if source string contains invalid UTF-16
  sequences. In such cases an empty string is returned. Encodings of char and wchar_t are UTF-8 and UTF-32 respectively.
  */
 template<CharTypeConvertibleWithNSString Char>
@@ -449,14 +449,14 @@ inline auto makeStdString(NSStringCharAccess::const_iterator first, NSStringChar
 /**
  Converts NSStringCharAccess or a view derived from it to `std::basic_string<Char>`
  
- @tparam Char character type of the resulatant std::basic_string
+ @tparam Char character type of the resultant std::basic_string
  
- A dervied view must produce the original view iterators. Thus, for example, `std::views::take(N) would work while
+ A derived view must produce the original view iterators. Thus, for example, `std::views::take(N) would work while
  `std::views::reverse` will not (and won't compile) since the latter's iterators are not the same as NSStringCharAccess ones.
  
- If iterators do not form a valid substring of some NSString the behavior is undefined. If first and alst are both uninitialized iterators the result is an empty string.
+ If iterators do not form a valid substring of some NSString the behavior is undefined. If first and last are both uninitialized iterators the result is an empty string.
  
- Convertions to char16_t are exact and never fail. Conversions to other character types are transcodings and can fail if source string contains invalid UTF-16
+ Conversions to char16_t are exact and never fail. Conversions to other character types are transcodings and can fail if source string contains invalid UTF-16
  sequences. In such cases an empty string is returned. Encodings of char and wchar_t are UTF-8 and UTF-32 respectively.
  */
 template<CharTypeConvertibleWithNSString Char, std::ranges::common_range Range>
@@ -472,7 +472,7 @@ inline auto makeStdString(Range && range) {
  
  The type of range's characters can be any of: char, char16_t, char32_t, char8_t, wchar_t.
  
- Convertions from char16_t are exact and can only fail if out of memory. Conversions from other character types are
+ Conversions from char16_t are exact and can only fail if out of memory. Conversions from other character types are
  transcodings and can fail if source string contains invalid UTF sequences. Encodings of char and wchar_t are UTF-8 and UTF-32 respectively.
  */
 template<std::ranges::contiguous_range CharRange>
@@ -496,7 +496,7 @@ inline auto makeCFString(const CharRange & range)  -> CFStringRef __nullable {
  
  The type of range's characters can be any of: char, char16_t, char32_t, char8_t, wchar_t.
  
- Convertions from char16_t are exact and can only fail if out of memory. Conversions from other character types are
+ Conversions from char16_t are exact and can only fail if out of memory. Conversions from other character types are
  transcodings and can fail if source string contains invalid UTF sequences. Encodings of char and wchar_t are UTF-8 and UTF-32 respectively.
  */
 template<CharTypeConvertibleWithNSString Char>
@@ -513,7 +513,7 @@ inline auto makeCFString(const Char * __nullable str) -> CFStringRef __nullable
  
  The type of range's characters can be any of: char, char16_t, char32_t, char8_t, wchar_t.
  
- Convertions from char16_t are exact and can only fail if out of memory. Conversions from other character types are
+ Conversions from char16_t are exact and can only fail if out of memory. Conversions from other character types are
  transcodings and can fail if source string contains invalid UTF sequences. Encodings of char and wchar_t are UTF-8 and UTF-32 respectively.
  */
 template<CharTypeConvertibleWithNSString Char>
@@ -531,7 +531,7 @@ inline auto makeCFString(const std::initializer_list<Char> & str) {
  
  The type of range's characters can be any of: char, char16_t, char32_t, char8_t, wchar_t.
  
- Convertions from char16_t are exact and can only fail if out of memory. Conversions from other character types are
+ Conversions from char16_t are exact and can only fail if out of memory. Conversions from other character types are
  transcodings and can fail if source string contains invalid UTF sequences. Encodings of char and wchar_t are UTF-8 and UTF-32 respectively.
  */
 template<std::ranges::contiguous_range CharRange>
@@ -547,7 +547,7 @@ inline auto makeNSString(const CharRange & range) {
  
  The type of range's characters can be any of: char, char16_t, char32_t, char8_t, wchar_t.
  
- Convertions from char16_t are exact and can only fail if out of memory. Conversions from other character types are
+ Conversions from char16_t are exact and can only fail if out of memory. Conversions from other character types are
  transcodings and can fail if source string contains invalid UTF sequences. Encodings of char and wchar_t are UTF-8 and UTF-32 respectively.
  */
 template<CharTypeConvertibleWithNSString Char>
@@ -562,7 +562,7 @@ inline auto makeNSString(const Char * __nullable str) {
  
  The type of range's characters can be any of: char, char16_t, char32_t, char8_t, wchar_t.
  
- Convertions from char16_t are exact and can only fail if out of memory. Conversions from other character types are
+ Conversions from char16_t are exact and can only fail if out of memory. Conversions from other character types are
  transcodings and can fail if source string contains invalid UTF sequences. Encodings of char and wchar_t are UTF-8 and UTF-32 respectively.
  */
 template<CharTypeConvertibleWithNSString Char>

diff --git a/include/objc-helpers/XCTestUtil.h b/include/objc-helpers/XCTestUtil.h
@@ -13,6 +13,8 @@
     #error This header requires C++20 mode or above with concepts support
 #endif
 
+#ifdef __OBJC__
+
 #import <XCTest/XCTest.h>
 
 #include <sstream>
@@ -102,5 +104,7 @@ namespace TestUtil {
     XCTPrimitiveAssertCpp(nil, >, _XCTAssertion_LessThanOrEqual, expression1, @#expression1, expression2, @#expression2, __VA_ARGS__)
 
 
+#endif //__OBJC__
+
 #endif