Add some doc strings

phpinspect-autoload.el

@@ -93,6 +93,9 @@
 qualified names congruent with a bareword type name. Keyed by
 bareword typenames."))
 
+(cl-defmethod phpinspect-autoloader-get-fqn-bag ((autoloader phpinspect-autoloader) name)
+  (gethash name (phpinspect-autoloader-type-name-fqn-bags autoloader)))
+
 (cl-defmethod phpinspect--read-json-file (fs file)
   (with-temp-buffer
     (phpinspect-fs-insert-file-contents fs file)

phpinspect-cache.el

@@ -337,10 +337,16 @@ then returned."
   (variables nil))
 
 (cl-defstruct (phpinspect-cache-namespace (:constructor phpinspect-make-cache-namespace))
+  (name nil
+        :type phpinspect-name)
+  (group nil
+         :type phpinspect-cache-group)
   (types nil)
   (functions nil))
 
 (cl-defstruct (phpinspect-cache-group (:constructor phpinspect-make-cache-group))
+  (autoloader nil
+              :type phpinspect-autoloader)
   (spec nil)
   (namespaces (make-hash-table :test #'eq :size 2000 :rehash-size 2.0))
   (extends (phpinspect-make-bidi-graph))
@@ -395,9 +401,12 @@ then returned."
 (defun phpinspect-cache-group-get-namespace (group namespace)
   (gethash namespace (phpinspect-cache-group-namespaces group)))
 
-(defun phpinspect-cache-group-get-namespace-create (group namespace)
-  (or (phpinspect-cache-group-get-namespace group namespace)
-      (puthash namespace (phpinspect-make-cache-namespace)
+(defun phpinspect-cache-group-get-namespace-create (group name)
+  "Retrieve namespace by NAME from GROUP.
+
+Name must be of type phpinspect-name (see `phpinspect-intern-name`)."
+  (or (phpinspect-cache-group-get-namespace group name)
+      (puthash name (phpinspect-make-cache-namespace :name name :group group)
                (phpinspect-cache-group-namespaces group))))
 
 (defun phpinspect-cache-namespace-get-type-create (namespace type category group)
@@ -411,14 +420,42 @@ then returned."
              (phpinspect-cache-namespace-types namespace)))))
 
 (defun phpinspect-cache-namespace-get-type (namespace type category)
-  (when-let ((entity
-              (cdr (assq (phpinspect--type-short-name type)
-                         (phpinspect-cache-namespace-types namespace)))))
-    (and (or (eq '@type category)
+  "Retrieve cached type metadata for TYPE attributed to CATEGORY from NAMESPACE.
+
+If an autoloader is available for the cache group that NAMESPACE
+belongs to and no in-memory match is found, the autoloader is
+queried and any resulting locations are indexed, after which the
+resulting metadata is returned."
+  (let* ((short-name (phpinspect--type-short-name type))
+         (namespace-name (phpinspect-cache-namespace-name namespace))
+         (autoloader (phpinspect-cache-group-autoloader
+                      (phpinspect-cache-namespace-group namespace)))
+         (entity (cdr (assq short-name
+                            (phpinspect-cache-namespace-types namespace)))))
+
+    ;; No entity was found in-memory, attempt to query autoloader when
+    ;; available.
+    (when (and (not entity) autoloader)
+      (let ((names (phpinspect-autoloader-get-fqn-bag autoloader namespace-name)))
+        (when (memq short-name names)
+          ;; ... parse/index type
+          (setq entity nil))))
+
+    ;; Only return types of the requested category
+    (and entity
+         (or (eq '@type category)
              (eq category (phpinspect-cache-type-category entity)))
          entity)))
 
+  ;; (when-let ((entity
+  ;;             (cdr (assq (phpinspect--type-short-name type)
+  ;;                        (phpinspect-cache-namespace-types namespace)))))
+  ;;   (and (or (eq '@type category)
+  ;;            (eq category (phpinspect-cache-type-category entity)))
+  ;;        entity)))
+
 (defun phpinspect-cache-namespace-delete-type (namespace type category)
+  "Delete TYPE attributed to CATEGORY from the in-memory cache of NAMESPACE."
   (let ((types (phpinspect-cache-namespace-types namespace))
         (name (phpinspect--type-short-name type))
         cell-before)
@@ -783,6 +820,11 @@ then returned."
    (t (error "Insert not supported for entity type %s" type))))
 
 (defun phpinspect-cache-query--do-get-type-wildcard (group param type namespace)
+  "Retrieve all type metadata matching TYPE and NAMESPACE available
+in the in-memory cache.
+
+This function does not query an autoloader even if it is
+available for the cache group."
   (let* ((all
           (if namespace
               (when-let ((namespace (phpinspect-cache-group-get-namespace group namespace)))
@@ -996,24 +1038,33 @@ then returned."
 (defun phpinspect-cache-query--compile-groups (cache group-specs intent)
   (cl-assert (phpinspect-cache-p cache))
   (let (groups)
-
-    (if group-specs
-        (dolist (spec group-specs)
-          (cl-assert (listp spec))
-          (cl-assert (memq (car spec) '(project label))
-                     t "Spec car must be the symbol `project' or `label'")
-          (let ((group (gethash spec (phpinspect-cache-groups cache))))
-            (when (and (eq :insert intent) (not group))
-              (setq group (puthash spec (phpinspect-make-cache-group :spec spec)
-                                   (phpinspect-cache-groups cache))))
-            (push group groups)))
-      (if (eq :insert intent)
-          (error "Cannot insert without defining cache group")
-        (setq groups (hash-table-values (phpinspect-cache-groups cache)))))
-
-    groups))
+    (if (phpinspect-cache-group-p cache)
+        (list cache)
+      (if group-specs
+          (dolist (spec group-specs)
+            (cl-assert (listp spec))
+            (cl-assert (memq (car spec) '(project label))
+                       t "Spec car must be the symbol `project' or `label'")
+            (let ((group (gethash spec (phpinspect-cache-groups cache))))
+              (when (and (eq :insert intent) (not group))
+                (setq group (puthash spec (phpinspect-make-cache-group :spec spec)
+                                     (phpinspect-cache-groups cache))))
+              (push group groups)))
+        (if (eq :insert intent)
+            (error "Cannot insert without defining cache group")
+          (setq groups (hash-table-values (phpinspect-cache-groups cache)))))
+
+      groups)))
 
 (defmacro phpinspect-cache-transact (cache group-specs &rest query)
+  "Execute QUERY on CACHE, filtering by GROUP-SPECS.
+
+CACHE must be an instance of `phpinspect-cache' or
+`phpinspect-cache-group'. If CACHE is a cache group, the query is
+only executed on this group and GROUP-SPECS is
+ignored. Otherwise, the groups in CACHE are filtered by
+GROUP-SPECS and each group in the resulting list of groups is
+subject of QUERY."
   (declare (indent 2))
   (cl-assert (listp query))
 
@@ -1068,7 +1119,6 @@ then returned."
 
     (let ((group-specs-sym (make-symbol "group-specs"))
           (intent-param-sym (make-symbol "intent-param"))
-          (cache-sym (make-symbol "cache"))
           (member-sym (make-symbol "member"))
           (namespace-sym (make-symbol "namespace"))
           (implements-sym (make-symbol "implements"))
@@ -1098,7 +1148,6 @@ then returned."
                  (lambda (val) val)
                  `((,group-specs-sym ,group-specs)
                    ,(unless (eq '* intent-param) `(,intent-param-sym ,intent-param))
-                   ,(when cache `(,cache-sym ,cache))
                    ,(when member `(,member-sym ,member))
                    ,(when namespace `(,namespace-sym ,namespace))
                    ,(when implements `(,implements-sym ,implements))