docs(action_manager): all equipped with doc strings

Signed-off-by: TsXor <[email protected]>

photoshop/api/_actionmanager_type_binder.py

@@ -19,6 +19,7 @@
 class ActionDescriptor(AD_proto, AD_utils_proto):
     @classmethod
     def load(cls, adict: dict) -> 'ActionDescriptor':
+        '''Convert a python object to an ActionDescriptor'''
         return super().load(adict, globals())
 
     def __init__(self, parent=None, classID=None):
@@ -45,6 +46,7 @@ def getReference(self, key: int) -> "ActionReference":
 class ActionList(AL_proto, AL_utils_proto):
     @classmethod
     def load(cls, alist: list) -> 'ActionList':
+        '''Convert a python object to an ActionList'''
         return super().load(alist, globals())
 
     def getType(self, index: int) -> DescValueType:
@@ -67,6 +69,7 @@ def getReference(self, index: int) -> "ActionReference":
 class ActionReference(AR_proto, AR_utils_proto):
     @classmethod
     def load(cls, adict: dict) -> 'ActionReference':
+        '''Convert a python object to an ActionReference'''
         return super().load(adict)
 
     def getForm(self) -> ReferenceFormType:

photoshop/api/action_manager/_main_types/_type_mapper.py

@@ -1,3 +1,7 @@
+'''Maybe the core of this submodule.
+Handles almost all type mappings. (Some else are in ReferenceKey.)
+This module is INTERNAL. You should not import functions from it.'''
+
 from ..desc_value_types import *
 from ..ref_form_types import *
 from ..utils import *

photoshop/api/action_manager/_main_types/action_descriptor.py

@@ -5,7 +5,9 @@
 from abc import ABC, abstractclassmethod
 
 class ActionDescriptor:
-  '''A vessel for my extra utils.'''
+  '''A vessel for my extra utils.
+  You should not use, and cannot initialize it
+  because it is an abstract class.'''
 
   @abstractclassmethod
   def load(cls, adict: dict, namespace: dict):  # pass globals() for namespace
@@ -23,11 +25,13 @@ def load(cls, adict: dict, namespace: dict):  # pass globals() for namespace
     return new
 
   def uget(self, key: str) -> Any:
+    '''Get a value of a key in an ActionDescriptor, no matter its type.'''
     keyid = str2id(key)
     val = pack(self, keyid)
     return val
 
   def uput(self, key: str, val: Any):
+    '''Put a value of a key into an ActionDescriptor, no matter its type.'''
     keyid = str2id(key)
     typestr, args = unpack(val)
     put_func = getattr(self, 'put'+typestr)
@@ -44,6 +48,7 @@ def __contains__(self, key):
     return key in keys
 
   def dump(self) -> dict:
+    '''Convert an ActionDescriptor to a python object.'''
     #This is a dict comprehension.
     ddict = {'_classID':self.classID}
     ddict.update({

photoshop/api/action_manager/_main_types/action_descriptor_iterator.py

@@ -1,6 +1,8 @@
 from ..utils import *
 
 class ActionDescriptor_Iterator:
+  '''An iterator. You don't need to initialize it manually.'''
+
   def __init__(self, psobj: 'ActionDescriptor'):
     self.curobj = psobj
     self.n = -1

photoshop/api/action_manager/_main_types/action_list.py

@@ -5,7 +5,9 @@
 from abc import ABC, abstractclassmethod
 
 class ActionList(ABC):
-  '''A vessel for my extra utils.'''
+  '''A vessel for my extra utils.
+  You should not use, and cannot initialize it
+  because it is an abstract class.'''
 
   @abstractclassmethod
   def load(cls, alist: list, namespace: dict):  # pass globals() for namespace
@@ -26,10 +28,12 @@ def dtype(self) -> str:
     return typestr
 
   def uget(self, index: int) -> Any:
+    '''Get an element in an ActionList, no matter its type.'''
     val = pack(self, index)
     return val
 
   def uput(self, val: Any):
+    '''Put an element into an ActionList, no matter its type.'''
     typestr, args = unpack(val)
     #ActionList type checking
     assert True if (dtype := self.dtype) is None else dtype == typestr, \
@@ -44,6 +48,7 @@ def __iter__(self) -> ActionList_Iterator:
     return ActionList_Iterator(self)
 
   def dump(self) -> list:
+    '''Convert an ActionList to a python object.'''
     #This is a list comprehension.
     dlist = [
       (

photoshop/api/action_manager/_main_types/action_list_iterator.py

@@ -1,6 +1,8 @@
 from typing import Any
 
 class ActionList_Iterator:
+  '''An iterator. You don't need to initialize it manually.'''
+
   def __init__(self, psobj: 'ActionList'):
     self.curobj = psobj
     self.n = -1

photoshop/api/action_manager/_main_types/action_reference.py

@@ -3,7 +3,9 @@
 from abc import ABC, abstractclassmethod
 
 class ActionReference(ABC):
-  '''A vessel for my extra utils.'''
+  '''A vessel for my extra utils.
+  You should not use, and cannot initialize it
+  because it is an abstract class.'''
 
   @abstractclassmethod
   def load(cls, alist: list):
@@ -19,6 +21,7 @@ def load(cls, alist: list):
     return new
 
   def uget(self, index: int) -> ReferenceKey:
+    '''Get a key in an ActionReference as ReferenceKey, no matter its type.'''
     target = self
     for i in range(index+1):
       try:
@@ -28,13 +31,15 @@ def uget(self, index: int) -> ReferenceKey:
     return ReferenceKey._packer(target)
 
   def uput(self, rkey: ReferenceKey):
+    '''Put a ReferenceKey into an ActionReference, no matter its type.'''
     assert type(rkey) == ReferenceKey
     ftype, dcls, v = rkey._unpacker()
     put_func = getattr(self, 'put'+ftype)
     args = (dcls,) if v is None else (dcls, *v)
     put_func(*args)
 
   def dump(self) -> list:
+    '''Convert an ActionReference to a python object.'''
     target = self
     tlist = ['!ref']
     tlist.extend([elem for elem in self])

photoshop/api/action_manager/_main_types/action_reference_iterator.py

@@ -1,6 +1,8 @@
 from ..ref_form_types import ReferenceKey
 
 class ActionReference_Iterator:
+  '''An iterator. You don't need to initialize it manually.'''
+
   def __init__(self, psobj: 'ActionReference'):
     self.curobj = psobj
     self.init = True

photoshop/api/action_manager/desc_value_types/enumerated.py

@@ -4,6 +4,7 @@
 Enumerated_proto = namedtuple('Enumerated_proto', ['type', 'value'])
 
 class Enumerated(Enumerated_proto):
+  '''You can initialize an Enumerated object with 2 arguments: type, value.'''
   @classmethod
   def _packer(cls, obj, index):
     type = id2str(obj.getEnumerationType(index))

photoshop/api/action_manager/desc_value_types/typeid.py

@@ -4,6 +4,7 @@
 TypeID_proto = namedtuple('TypeID_proto', ['string'])
 
 class TypeID(TypeID_proto):
+  '''You can initialize a TypeID object with 1 argument: string.'''
   @classmethod
   def _packer(cls, obj, index):
     typeid = id2str(obj.getClass(index))

photoshop/api/action_manager/desc_value_types/unitdouble.py

@@ -4,6 +4,7 @@
 UnitDouble_proto = namedtuple('UnitDouble_proto', ['unit', 'double'])
 
 class UnitDouble(UnitDouble_proto):
+  '''You can initialize a UnitDouble object with 2 arguments: unit, double.'''
   @classmethod
   def _packer(cls, obj, index):
     unit = id2str(obj.getUnitDoubleType(index))

photoshop/api/action_manager/jprint.py

@@ -1,7 +1,8 @@
-#Format it like json!
-#Just literal processing.
+'''Format a repr() string like json.
+This is just literal processing.'''
 
 def jformat(astr, indent=4, prefix=None):
+  '''Formats a repr() string.'''
   all_am_keywords = [  # noqa: F405
     'str2id',
     'id2str',
@@ -56,4 +57,5 @@ def jformat(astr, indent=4, prefix=None):
   return nstr
 
 def jprint(obj, indent=4):
+  '''Print formatted repr of an object.'''
   print(jformat(repr(obj), indent=indent))

photoshop/api/action_manager/js_converter/convert.py

@@ -1,3 +1,8 @@
+'''Defines functions to parse information got on the js side into loadable form.
+Use with following: (You need to install Node.js to PATH!)
+import photoshop.api.action_manager as am
+am.dumpjs(some_js_code)'''
+
 from .node_execjs import execjs
 from .injection_js import injection
 from ..utils import str2id, id2str, str2hash, hash2str

photoshop/api/action_manager/js_converter/injection_js.py

@@ -1,4 +1,8 @@
-#You may turn on syntax highlighting for js here.
+'''Defines injection, a variable which contains js code.
+These js code implements Photoshop functions, and lures a piece of js code
+to output all its information on executing executeAction function.
+You may turn on syntax highlighting for js here.'''
+
 injection = '''
 
 class UnitDouble {

photoshop/api/action_manager/js_converter/node_execjs.py

@@ -1,3 +1,5 @@
+'''Defines execjs, a function to run js in Node.js'''
+
 import os,re,subprocess
 
 # Node.js check

photoshop/api/action_manager/ref_form_types/_marker.py

@@ -1,3 +1,6 @@
+'''Defines class marker. It is the class of Identifier, Index, Offset.
+It is INTERNAL. You should not import or initialize it.'''
+
 class marker:
   def __init__(self, name, value=0):
     self.name = name

photoshop/api/action_manager/ref_form_types/identifier.py

@@ -1,3 +1,7 @@
+'''Defines a special object: Identifier.
+You can give it a value by adding a number to it.
+For example: id = Identifier+777'''
+
 from ._marker import marker
 
 Identifier = marker('Identifier')

photoshop/api/action_manager/ref_form_types/index.py

@@ -1,3 +1,7 @@
+'''Defines a special object: Index.
+You can give it a value by adding a number to it.
+For example: index = Index+1'''
+
 from ._marker import marker
 
 Index = marker('Index')

photoshop/api/action_manager/ref_form_types/offset.py

@@ -1,3 +1,7 @@
+'''Defines a special object: Offset.
+You can give it a value by adding a number to it.
+For example: offset = Offset+12'''
+
 from ._marker import marker
 
 Offset = marker('Offset')

photoshop/api/action_manager/ref_form_types/referencekey.py

@@ -1,3 +1,6 @@
+'''Defines class ReferenceKey. It handles type mapping in ActionReference.
+You can initialize it with 2 arguments: desiredclass, value.'''
+
 from ..utils import *
 from ..desc_value_types import TypeID, Enumerated
 from photoshop.api.enumerations import ReferenceFormType

photoshop/api/action_manager/utils.py

@@ -1,8 +1,11 @@
+'''TypeID conversion utilities of this submodule.'''
+
 from photoshop.api._core import Photoshop
 
 __all__ = ['str2id', 'id2str']
 
 class app(Photoshop):
+  '''Partially reimplement the Application class in this file to avoid circular import.'''
   typename = 'Application'
   def str2id(self, string: str) -> int:
     return self.app.stringIDToTypeID(string)