comments

[toc] / src / find.h

diff --git a/src/find.h b/src/find.h
index 3342536b1a05bfcc99bdd6396bb164c2a39e2889..cd7f5773901542f8d518614cdc1a17ddbccef123 100644 (file)
--- a/src/find.h
+++ b/src/find.h
@@ -8,7 +8,10 @@
 \r
 template<typename T>\r
 using opt = std::optional<T>;\r
+template<typename ... Ts>\r
+using tup = std::tuple<Ts ...>;\r
 \r
+// find an item in a vector by predicate\r
 template<typename T>\r
 opt<T> find(const std::vector<T> & ts, std::function<bool(T)> f)\r
 {\r
@@ -18,6 +21,7 @@ opt<T> find(const std::vector<T> & ts, std::function<bool(T)> f)
   return nullopt;\r
 }\r
 \r
+// same as above but return pointer into raw array held by vector\r
 template<typename T>\r
 opt<T *> findPtr(const std::vector<T> & ts, std::function<bool(T)> f)\r
 {\r
@@ -27,12 +31,12 @@ opt<T *> findPtr(const std::vector<T> & ts, std::function<bool(T)> f)
   return nullopt;\r
 }\r
 \r
-std::optional<\r
-  std::tuple<\r
-    std::shared_ptr<Context>,\r
-    std::vector<std::string>>>\r
+opt<tup<\r
+        std::shared_ptr<Context>,\r
+        std::vector<std::string>>>\r
 getContext(std::shared_ptr<Context> ctx, const std::vector<std::string> & namespacePrefix)\r
 {\r
+  // try finding a continuos series of namespaces in a given context\r
   auto result = ctx;\r
 \r
   for (auto name : namespacePrefix)\r
@@ -48,6 +52,8 @@ getContext(std::shared_ptr<Context> ctx, const std::vector<std::string> & namesp
     }\r
   }\r
 \r
+  // if the found context is the end of a series of namespaces, also return\r
+  // a vector of namespace names\r
   std::vector<std::string> namespaces;\r
   for (auto it = result; it != nullptr; it = it->parent)\r
   {\r
@@ -65,9 +71,13 @@ getContext(std::shared_ptr<Context> ctx, const std::vector<std::string> & namesp
   return std::make_tuple(result, namespaces);\r
 }\r
 \r
+// all of the following functions work the same way,\r
+// walking up the context hierarchy until the global context.\r
+// return the first found instance that matches provided criteria\r
+// theres also a variant to get a pointer instead for functions and\r
+// structs used for generic instantiation\r
 \r
-\r
-opt<std::tuple<Function, std::vector<std::string>>> findFunction(\r
+opt<tup<Function, std::vector<std::string>>> findFunction(\r
   const std::string & name,\r
   const std::vector<std::string> & namespacePrefix,\r
   std::shared_ptr<Context> ctx)\r
@@ -85,7 +95,7 @@ opt<std::tuple<Function, std::vector<std::string>>> findFunction(
   return nullopt;\r
 }\r
 \r
-opt<std::tuple<Function *, std::vector<std::string>>> findFunctionPtr(\r
+opt<tup<Function *, std::vector<std::string>>> findFunctionPtr(\r
   const std::string & name,\r
   const std::vector<std::string> & namespacePrefix,\r
   std::shared_ptr<Context> ctx)\r
@@ -105,7 +115,7 @@ opt<std::tuple<Function *, std::vector<std::string>>> findFunctionPtr(
 \r
 \r
 \r
-opt<std::tuple<Struct, std::vector<std::string>>> findStruct(\r
+opt<tup<Struct, std::vector<std::string>>> findStruct(\r
   const std::string & name,\r
   const std::vector<std::string> & namespacePrefix,\r
   std::shared_ptr<Context> ctx)\r
@@ -123,7 +133,7 @@ opt<std::tuple<Struct, std::vector<std::string>>> findStruct(
   return nullopt;\r
 }\r
 \r
-opt<std::tuple<Struct *, std::vector<std::string>>> findStructPtr(\r
+opt<tup<Struct *, std::vector<std::string>>> findStructPtr(\r
   const std::string & name,\r
   const std::vector<std::string> & namespacePrefix,\r
   std::shared_ptr<Context> ctx)\r
@@ -143,7 +153,7 @@ opt<std::tuple<Struct *, std::vector<std::string>>> findStructPtr(
 \r
 \r
 \r
-opt<std::tuple<Variable, std::vector<std::string>>> findVariable(\r
+opt<tup<Variable, std::vector<std::string>>> findVariable(\r
   const std::string & name,\r
   const std::vector<std::string> & namespacePrefix,\r
   std::shared_ptr<Context> ctx)\r
@@ -163,6 +173,8 @@ opt<std::tuple<Variable, std::vector<std::string>>> findVariable(
 \r
 \r
 \r
+// find struct members and pointer variants\r
+\r
 opt<StructMember<Function>> findStructMethod(\r
   const std::string & name,\r
   const Struct & s)\r