Update help text and add docstring #102

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

product_portfolio/migrations/0010_productcomponent_weighted_risk_score_and_more.py

@@ -14,7 +14,7 @@ class Migration(migrations.Migration):
         migrations.AddField(
             model_name='productcomponent',
             name='weighted_risk_score',
-            field=models.DecimalField(blank=True, decimal_places=1, help_text='Risk score from 0.0 to 10.0, with higher values indicating greater vulnerability risk. This score is the maximum of the weighted severity multiplied by exploitability, capped at 10, which is then multiplied by the associated exposure risk factor assigned to the product item purpose (when available).', max_digits=3, null=True),
+            field=models.DecimalField(blank=True, decimal_places=1, help_text="Risk score (0.0 to 10.0), where higher values indicate greater vulnerability. Calculated as the weighted severity times exploitability (capped at 10), adjusted by the exposure risk factor of the product item's purpose.", max_digits=3, null=True),
         ),
         migrations.AddField(
             model_name='productitempurpose',
@@ -24,7 +24,7 @@ class Migration(migrations.Migration):
         migrations.AddField(
             model_name='productpackage',
             name='weighted_risk_score',
-            field=models.DecimalField(blank=True, decimal_places=1, help_text='Risk score from 0.0 to 10.0, with higher values indicating greater vulnerability risk. This score is the maximum of the weighted severity multiplied by exploitability, capped at 10, which is then multiplied by the associated exposure risk factor assigned to the product item purpose (when available).', max_digits=3, null=True),
+            field=models.DecimalField(blank=True, decimal_places=1, help_text="Risk score (0.0 to 10.0), where higher values indicate greater vulnerability. Calculated as the weighted severity times exploitability (capped at 10), adjusted by the exposure risk factor of the product item's purpose.", max_digits=3, null=True),
         ),
         migrations.RunSQL(
             """

product_portfolio/models.py

@@ -709,15 +709,11 @@ def annotate_weighted_risk_score(self):
 
     def update_weighted_risk_score(self):
         """
-        Updates the `weighted_risk_score` for all objects in the queryset.
+        Update the `weighted_risk_score` for all objects in the queryset.
 
         This directly writes to the database and doesn't trigger model `save()`
         methods, so any side effects in `save()` won't be executed.
         """
-        """
-        Update the weighted_risk_score using the computed annotation from
-        `self.annotate_weighted_risk_score()`
-        """
         return self.annotate_weighted_risk_score().update(
             weighted_risk_score=F("computed_weighted_risk_score"),
         )
@@ -781,11 +777,9 @@ class ProductRelationshipMixin(
         max_digits=3,
         decimal_places=1,
         help_text=_(
-            "Risk score from 0.0 to 10.0, with higher values indicating greater "
-            "vulnerability risk. This score is the maximum of the weighted severity "
-            "multiplied by exploitability, capped at 10, which is then multiplied by "
-            "the associated exposure risk factor assigned to the product item "
-            "purpose (when available)."
+            "Risk score (0.0 to 10.0), where higher values indicate greater vulnerability. "
+            "Calculated as the weighted severity times exploitability (capped at 10), "
+            "adjusted by the exposure risk factor of the product item's purpose."
         ),
     )
 
@@ -820,6 +814,17 @@ def get_status_from_item_policy(self):
                     return status
 
     def compute_weighted_risk_score(self):
+        """
+        Compute the weighted risk score for the current instance.
+
+        The weighted risk score is calculated as:
+            - `risk_score` of the related component or package,
+            - Multiplied by the `exposure_factor` of the item's purpose
+              (defaulting to 1.0 if unavailable).
+
+        If the related object does not exist or its `risk_score` is `None`,
+        the method returns `None`.
+        """
         related_object = self.related_component_or_package
         if not related_object:  # Custom component
             return None
@@ -836,6 +841,15 @@ def compute_weighted_risk_score(self):
         return weighted_risk_score
 
     def set_weighted_risk_score(self):
+        """
+        Update the `weighted_risk_score` for the current instance.
+
+        The method computes the weighted risk score using `compute_weighted_risk_score()`
+        and assigns the computed value to the `weighted_risk_score` field if it differs
+        from the current value.
+
+        This ensures that the field reflects the most up-to-date calculation.
+        """
         weighted_risk_score = self.compute_weighted_risk_score()
         if weighted_risk_score != self.weighted_risk_score:
             self.weighted_risk_score = weighted_risk_score