From 67ed40b65f282814b4487850926e6f7df2cef7ac Mon Sep 17 00:00:00 2001
From: Winston Chang <winston@stdout.org>
Date: Mon, 17 Jul 2023 11:32:26 -0500
Subject: [PATCH] Add docstring for classification_label

---
 js/ml/classification-label.ts |  3 ++-
 shiny/ui/ml.py                | 39 ++++++++++++++++++++++++++++-------
 2 files changed, 34 insertions(+), 8 deletions(-)

diff --git a/js/ml/classification-label.ts b/js/ml/classification-label.ts
index 800ef26e5..c92bc592d 100644
--- a/js/ml/classification-label.ts
+++ b/js/ml/classification-label.ts
@@ -54,6 +54,7 @@ export class ShinyClassificationLabel extends LitElement {
   displayWinner: number = 0;
   @property({ type: Number, attribute: "max-items" })
   maxItems: number | null = null;
+  @property({ type: String, attribute: "suffix" }) suffix: string = "%";
 
   render() {
     let entries = Object.entries(this.value);
@@ -81,7 +82,7 @@ export class ShinyClassificationLabel extends LitElement {
 
     const valuesHtml = entries.map(([k, v]) => {
       return html`<div class="item">
-        <div class="bar" style="width: ${v}%;"></div>
+        <div class="bar" style="width: ${v}${this.suffix};"></div>
         <div class="label">
           <div>${k}</div>
           <div class="dashed-line"></div>
diff --git a/shiny/ui/ml.py b/shiny/ui/ml.py
index 5264743f9..fb709900b 100644
--- a/shiny/ui/ml.py
+++ b/shiny/ui/ml.py
@@ -6,23 +6,49 @@
 
 import json
 
-from htmltools import HTML, HTMLDependency, Tag, TagAttrValue, html_escape
+from htmltools import HTML, HTMLDependency, Tag, html_escape
 
 from .. import __version__
 
 # from .._docstring import add_example
-# from .._namespaces import resolve_id
 
 
 def classification_label(
     value: dict[str, float],
     *,
-    sort: Optional[bool] = None,
+    sort: bool = True,
     display_winner: Optional[bool] = None,
     max_items: Optional[int] = None,
-    _add_ws: bool = True,
-    **kwargs: TagAttrValue,
+    suffix: str = "%",
 ) -> Tag:
+    """
+    Create a classification label with confidence scores.
+
+    This is meant to be used to display classification results from a model. The
+    component itself is static, so to display dynamic values, it would typically be used
+    with a :func:`~shiny.ui.ouput_ui` and :func:`~shiny.render.ui`.
+
+    Parameters
+    ----------
+    value
+        A dictionary with class names as keys and and confidence scores as values.
+    sort
+        Should the values be sorted? Defaults to ``True``.
+    display_winner:
+        If ``True`` (the default), then the name of the winner will be displayed above
+        the values, in larger text.
+    max_items:
+        The maximum number of items to display. Defaults to ``None``, which means all
+        items will be displayed.
+    suffix:
+        A string to place after each value. Defaults to ``"%"``.
+    _add_ws:
+
+    Returns
+    -------
+    :
+        A UI element.
+    """
     return Tag(
         "shiny-classification-label",
         ml_dep(),
@@ -30,8 +56,7 @@ def classification_label(
         sort=bool_to_num(sort),
         display_winner=bool_to_num(display_winner),
         max_items=max_items,
-        _add_ws=_add_ws,
-        **kwargs,
+        suffix=suffix,
     )