From efa3e9904b5497569d92fa1e34a10ed8c0ca854c Mon Sep 17 00:00:00 2001 From: Yannick Uhlmann Date: Tue, 6 Feb 2024 16:34:16 +0100 Subject: [PATCH] more documentation :nerd: --- docs/util/util.html | 123 +++++++++++++++++++++++++++++++------------- yal/util/util.py | 50 ++++++++++++------ 2 files changed, 121 insertions(+), 52 deletions(-) diff --git a/docs/util/util.html b/docs/util/util.html index 77ede3a..f15cce0 100644 --- a/docs/util/util.html +++ b/docs/util/util.html @@ -91,21 +91,21 @@

Module yal.util.util

Return: - A dictionary of the form: - - ``` - { 'idx': Module.module_name - , 'xmin': <lower left x coordinate> - , 'ymin': <lower left y coordinate> - , 'width': <width of module> - , 'height': <height of module> - , 'clashes': {} - , 'aversions': {} - , 'inference': 0 - , 'connections': {<other idx>: <weight>} - , 'turmoil': 0 - , 'wounds': [] } - ``` + A dictionary of the form: + + ``` + { 'idx': Module.module_name + , 'xmin': <lower left x coordinate> + , 'ymin': <lower left y coordinate> + , 'width': <width of module> + , 'height': <height of module> + , 'clashes': {} + , 'aversions': {} + , 'inference': 0 + , 'connections': {<other idx>: <weight>} + , 'turmoil': 0 + , 'wounds': [] } + ``` """ dims = sorted(module.dimensions) @@ -126,9 +126,23 @@

Module yal.util.util

return participant -def connects(participant, participants) -> set[str]: +def connects(participant: dict, participants: list[dict]) -> dict[str,int]: """ Weighted connections between participants + + Arguments: + + - `participant`: The participant in question + + - `participants`: Other participants (can include the former) + + Return: + + A dictionary of the form: + + ``` + {'other participant': <weight of connection>} + ``` """ name = participant['module_name'] sigs = set(participant.get('signal_names', [])) @@ -167,6 +181,10 @@

Module yal.util.util

field (optional, default = `False`) - `critical_nets`: Whether to retain the `yal.core.Module.critical_nets` field (optional, default = `False`) + + Return: + + A list of participant dictionaries. """ all_fields = zip( [ module_type, dimensions, terminals @@ -219,7 +237,7 @@

Functions

  • colorize: Whether to add a random color to the participant. Otherwise the 'color' field is None. (optional, default = True)
    • -

    Return

    +

    Return:

    A dictionary of the form:

    { 'idx':         Module.module_name
 , 'xmin':        <lower left x coordinate>
@@ -254,21 +272,21 @@ 
    Return
    
 
     Return:
 
-        A dictionary of the form:
-
-        ```
-        { 'idx':         Module.module_name
-        , 'xmin':        <lower left x coordinate>
-        , 'ymin':        <lower left y coordinate>
-        , 'width':       <width of module>
-        , 'height':      <height of module>
-        , 'clashes':     {}
-        , 'aversions':   {}
-        , 'inference':   0
-        , 'connections': {<other idx>: <weight>}
-        , 'turmoil':     0
-        , 'wounds':      [] }
-        ```
+    A dictionary of the form:
+
+    ```
+    { 'idx':         Module.module_name
+    , 'xmin':        <lower left x coordinate>
+    , 'ymin':        <lower left y coordinate>
+    , 'width':       <width of module>
+    , 'height':      <height of module>
+    , 'clashes':     {}
+    , 'aversions':   {}
+    , 'inference':   0
+    , 'connections': {<other idx>: <weight>}
+    , 'turmoil':     0
+    , 'wounds':      [] }
+    ```
     """
 
     dims        = sorted(module.dimensions)
@@ -313,7 +331,9 @@ 
    Return
    
 field (optional, default = False)
 
  • critical_nets: Whether to retain the Module.critical_nets field
 (optional, default = False)
    • 
-
+
+
    Return:
    
+
    A list of participant dictionaries.
    
 
    
 
 Expand source code
@@ -349,6 +369,10 @@ 
    Return
    
         field (optional, default = `False`)
     - `critical_nets`: Whether to retain the `yal.core.Module.critical_nets` field
         (optional, default = `False`)
+
+    Return:
+    
+    A list of participant dictionaries.
     """
 
     all_fields = zip( [ module_type, dimensions, terminals
@@ -380,17 +404,44 @@ 
    Return
    
 
    
 
 
    
-def connects(participant, participants) ‑> set[str]
+def connects(participant: dict, participants: list[dict]) ‑> dict[str, int]
 
    
 
    
-
    Weighted connections between participants
    
+
    Weighted connections between participants
    
+
    Arguments:
    
+
      
+
    • 
+
      participant: The participant in question
      
+
      • 
+
    • 
+
      participants: Other participants (can include the former)
      
+
      • 
+
    
+
    Return:
    
+
    A dictionary of the form:
    
+
    {'other participant': <weight of connection>}
+
    
 
    
 
 Expand source code
 
-
    def connects(participant, participants) -> set[str]:
+
    def connects(participant: dict, participants: list[dict]) -> dict[str,int]:
     """
     Weighted connections between participants
+
+    Arguments:
+
+    - `participant`: The participant in question
+
+    - `participants`: Other participants (can include the former)
+
+    Return:
+
+    A dictionary of the form:
+
+    ```
+    {'other participant': <weight of connection>}
+    ```
     """
     name = participant['module_name']
     sigs = set(participant.get('signal_names', []))
diff --git a/yal/util/util.py b/yal/util/util.py
index 5ac4907..7e8b512 100644
--- a/yal/util/util.py
+++ b/yal/util/util.py
@@ -61,21 +61,21 @@ def as_participant( module: core.Module, opt_fields: list[str] = None
 
     Return:
 
-        A dictionary of the form:
-
-        ```
-        { 'idx':         Module.module_name
-        , 'xmin':        
-        , 'ymin':        
-        , 'width':       
-        , 'height':      
-        , 'clashes':     {}
-        , 'aversions':   {}
-        , 'inference':   0
-        , 'connections': {: }
-        , 'turmoil':     0
-        , 'wounds':      [] }
-        ```
+    A dictionary of the form:
+
+    ```
+    { 'idx':         Module.module_name
+    , 'xmin':        
+    , 'ymin':        
+    , 'width':       
+    , 'height':      
+    , 'clashes':     {}
+    , 'aversions':   {}
+    , 'inference':   0
+    , 'connections': {: }
+    , 'turmoil':     0
+    , 'wounds':      [] }
+    ```
     """
 
     dims        = sorted(module.dimensions)
@@ -96,9 +96,23 @@ def as_participant( module: core.Module, opt_fields: list[str] = None
 
     return participant
 
-def connects(participant, participants) -> set[str]:
+def connects(participant: dict, participants: list[dict]) -> dict[str,int]:
     """
     Weighted connections between participants
+
+    Arguments:
+
+    - `participant`: The participant in question
+
+    - `participants`: Other participants (can include the former)
+
+    Return:
+
+    A dictionary of the form:
+
+    ```
+    {'other participant': }
+    ```
     """
     name = participant['module_name']
     sigs = set(participant.get('signal_names', []))
@@ -137,6 +151,10 @@ def as_participants( modules: list[core.Module]
         field (optional, default = `False`)
     - `critical_nets`: Whether to retain the `yal.core.Module.critical_nets` field
         (optional, default = `False`)
+
+    Return:
+    
+    A list of participant dictionaries.
     """
 
     all_fields = zip( [ module_type, dimensions, terminals