[WIP] added doc strings

shiny_semantic/elements/button.py

@@ -15,6 +15,31 @@ def button(
     class_: Optional[str] = None,
     **kwargs: TagAttrArg,
 ):
+    """
+    Generate an HTML button element with optional icon and attributes.
+
+    This function generates an HTML button element with various customization options,
+    including providing an icon, setting CSS classes, and adding additional attributes.
+
+    Args:
+        id (str): The unique identifier for the button.
+        label (str, optional): The text label to display on the button. If not provided, the button will be icon-only.
+        icon (TagChildArg, optional): An HTML element representing an icon to be displayed on the button.
+        class_ (str, optional): Additional CSS classes to be applied to the button element.
+        **kwargs (TagAttrArg): Additional attributes to be added to the button element.
+
+    Returns:
+        str: A string representing the generated HTML button element.
+
+    Example:
+        # Creating a button with text label
+        button_with_label = button("my_button", label="Click Me", class_="primary", onclick="handle_click()")
+
+        # Creating an icon-only button
+        icon_element = tags.i(class_="fas fa-search")
+        icon_button = button("search_button", icon=icon_element, class_="icon-button")
+
+    """
     class_name = f"ui {class_ or ''} button"
 
     return tags.button(
@@ -33,6 +58,34 @@ def update_button(
     icon_name: Optional[str] = None,
     session: Optional[Session] = None,
 ):
+    """
+    Update a button in an active session.
+
+    This function updates the properties of a button element in a given active session.
+    The input_id is used to identify the specific button element to be updated. The label
+    and icon_name arguments can be provided to change the label text and icon of the button,
+    respectively.
+
+    Args:
+        input_id (str): The ID of the button element to be updated.
+        label (str, optional): The new label text for the button. If not provided, the label remains unchanged.
+        icon_name (str, optional): The name of the icon to be displayed on the button. If not provided,
+            the icon remains unchanged.
+        session (Session, optional): An active session instance in which the button is located.
+            If not provided, the function attempts to use the default active session.
+
+    Returns:
+        None
+
+    Example:
+        update_button(
+          "my_button",
+          label = "Click Me",
+          icon_name = "icon-check",
+          session = session
+        )
+
+    """
     session = require_active_session(session)
     msg = {
         "label": label,

shiny_semantic/elements/container.py

@@ -10,6 +10,36 @@ def container(
     class_: Optional[str] = None,
     **kwargs: TagAttrArg,
 ):
+    """
+    Create a container HTML element with optional classes and attributes.
+
+    This function generates an HTML <div> element with the specified
+    content elements as children.
+    It can be used to encapsulate content within a container, often used
+    in web design frameworks.
+
+    Args:
+        *children (TagChildArg): Variable number of content elements
+        to be included inside the container.
+        class_ (str, optional): Additional classes to be added
+        to the container's class attribute.
+            Default is None.
+        **kwargs (TagAttrArg): Additional attributes to be added
+        to the container element.
+
+    Returns:
+        str: A string representing the generated HTML container element.
+
+    Example:
+        container_content = tags.p("This is content inside the container.")
+        container_element = container(
+          container_content,
+          class_ = "my-custom-class",
+          id = "container1"
+        )
+        print(container_element)
+
+    """
     return tags.div(
         *children,
         class_=squash_whitespace(f"ui {class_ or ''} container"),

shiny_semantic/elements/divider.py

@@ -10,6 +10,32 @@ def divider(
     class_: Optional[str] = None,
     **kwargs: TagAttrArg,
 ):
+    """
+    Generate a UI divider element with optional content and attributes.
+
+    This function creates a <div> element styled as a UI divider, commonly used in user interfaces
+    to visually separate content. You can provide optional children elements to include content
+    within the divider, and you can also customize the styling and attributes of the divider.
+
+    Args:
+        *children (TagChildArg): Variable number of HTML content elements to be placed inside the divider.
+        class_ (str, optional): Additional CSS class to apply to the divider for custom styling.
+        **kwargs (TagAttrArg): Additional HTML attributes to apply to the <div> element.
+
+    Returns:
+        str: A string representing the generated HTML <div> element.
+
+    Example:
+        div_content = tags.p("This is some content within the divider.")
+        div_attributes = {"id": "my-divider", "data-role": "separator"}
+        divider_element = divider(
+          div_content,
+          class_ = "custom-divider",
+          **div_attributes
+        )
+        print(divider_element)
+
+    """
     return tags.div(
         *children,
         class_=squash_whitespace(f"ui {class_ or ''} divider"),

shiny_semantic/elements/emoji.py

@@ -4,4 +4,27 @@
 
 
 def emoji(emoji_name: str, *, class_: Optional[str] = None, **kwargs: TagAttrArg):
+    """
+    Generate an <em> (emphasis) HTML tag representing an emoji.
+
+    This function creates an HTML <em> tag that displays an emoji by using its name. The emoji name is enclosed in colons
+    and should match a valid emoji name supported by the underlying system or library.
+
+    Args:
+        emoji_name (str): The name of the emoji, without colons. For example, "smile" for ":smile:".
+        class_ (str, optional): CSS class to apply to the <em> tag for styling purposes. Defaults to None.
+        **kwargs: Additional keyword arguments that will be added as attributes to the <em> tag.
+
+    Returns:
+        str: A string representing the generated <em> tag containing the specified emoji.
+
+    Example:
+        emoji_tag = emoji(
+          "smile",
+          class_ = "highlight",
+          title = "Happy Face"
+        )
+        print(emoji_tag)
+
+    """
     return tags.em(data_emoji=f":{emoji_name}:", class_=class_, **kwargs)

shiny_semantic/elements/flag.py

@@ -6,6 +6,29 @@
 
 
 def flag(country: str, *, class_: Optional[str] = None, **kwargs: TagAttrArg):
+    """
+    Generate an inline flag icon element for a specified country.
+
+    This function generates an inline <i> element with a CSS class representing a flag icon
+    for the specified country. Additional HTML attributes can be provided using keyword arguments.
+
+    Args:
+        country (str): The name of the country for which the flag icon should be displayed.
+        class_ (str, optional): Additional CSS class to be applied to the flag icon. Defaults to None.
+        **kwargs: Additional HTML attributes to be added to the <i> element.
+
+    Returns:
+        str: A string representing the generated <i> element with the flag icon and attributes.
+
+    Example:
+        flag_element = flag(
+          "usa",
+          class_ = "large-flag",
+          title = "USA Flag"
+        )
+        print(flag_element)
+
+    """
     return tags.i(
         class_=squash_whitespace(f"{class_ or ''} {country} flag"),
         **kwargs,

shiny_semantic/elements/header.py

@@ -16,6 +16,27 @@ def header(
     class_: Optional[str] = None,
     **kwargs: TagAttrArg,
 ):
+    """
+    Generate a semantic header element with optional UI classes.
+
+    This function creates an HTML <div> element with the specified content children and optional
+    UI classes for styling. The generated <div> acts as a header element, often used to display
+    headings or titles within a user interface.
+
+    Args:
+        *children (TagChildArg): Variable number of HTML content elements to be included within the header.
+        class_ (str, optional): Additional CSS classes to be applied to the header element.
+        **kwargs (TagAttrArg): Additional keyword arguments to be added as attributes to the header element.
+
+    Returns:
+        str: A string representing the generated HTML header element.
+
+    Example:
+        header_content = tags.h1("Welcome to My App!")
+        header_element = header(header_content, class_="highlight", id="app-header")
+        print(header_element)
+
+    """
     return tags.div(
         *children,
         class_=squash_whitespace(f"ui {class_ or ''} header"),
@@ -28,6 +49,31 @@ def subheader(
     class_: Optional[str] = None,
     **kwargs: TagAttrArg,
 ):
+    """
+    Create a subheader HTML element with optional classes and attributes.
+
+    This function generates an HTML <div> element to represent a subheader. It allows
+    specifying child elements to be included within the subheader, along with optional
+    classes and additional HTML attributes.
+
+    Args:
+        *children (TagChildArg): Variable number of child elements to be included within the subheader.
+        class_ (str, optional): CSS class(es) to be applied to the subheader. Multiple classes can be provided
+            by separating them with a space. The "sub header" class is automatically added to the specified classes.
+        **kwargs (TagAttrArg): Additional HTML attributes to be applied to the subheader.
+
+    Returns:
+        str: A string representing the generated subheader HTML element.
+
+    Example:
+        subheader_element = subheader(
+          tags.h2("Important Information"),
+          class_ = "highlight",
+          id = "info-header"
+        )
+        print(subheader_element)
+
+    """
     return tags.div(
         *children,
         class_=squash_whitespace(f"{class_ or ''} sub header"),

shiny_semantic/elements/icon.py

@@ -11,6 +11,35 @@ def icon(
     class_: Optional[str] = None,
     **kwargs: TagAttrArg,
 ):
+    """
+    Generate an HTML <i> element with an icon.
+
+    This function creates an HTML <i> element that is commonly used for displaying icons using icon classes.
+    The icon_name parameter specifies the icon class to be applied to the <i> element.
+    Additional attributes can be passed using the kwargs parameter.
+
+    Args:
+        icon_name (str): The icon class name to be applied to the <i> element.
+        class_ (str, optional): Additional CSS class(es) to be added to the <i> element.
+            If not provided, only the icon class specified by icon_name will be used.
+        **kwargs: Additional keyword arguments representing attributes to be added to the <i> element.
+
+    Returns:
+        dominate.tags.i: An HTML <i> element with the specified icon class and optional attributes.
+
+    Example:
+        # Creating a simple icon element
+        simple_icon = icon("fa fa-star")
+
+        # Creating an icon element with additional classes and attributes
+        custom_icon = icon(
+          "my-icon",
+          class_ = "custom-icon",
+          title = "Custom Icon",
+          aria_label = "Custom"
+        )
+
+    """
     return tags.i(
         class_=squash_whitespace(f"{class_ or ''} {icon_name} icon"),
         **kwargs,

shiny_semantic/elements/input.py

@@ -18,11 +18,41 @@ def semantic_input(
     semantic_label_class: Optional[str] = None,
     **kwargs: TagAttrArg,
 ):
-    """Keyword arguments (**kwargs) include all html attributes
-    relevant to the input tag, including, for example, `min`, `max` and `step`
-    in case of input type="number", as well as `class_` that is passed directly
-    to the input tag, as opposed to the `semantic_class` that is passed to the
-    enclosing div element.
+    """
+    Generate a semantic-styled input element with optional label and icon.
+
+    This function generates a customizable HTML input element with a semantic styling,
+    allowing for the addition of icons, labels, and various attributes. The input
+    element is enclosed in a <div> element with appropriate classes for styling.
+
+    Args:
+        id (str): Identifier for the input element.
+        value (Union[str, float], optional): Initial value of the input element. Defaults to an empty string.
+        placeholder (str, optional): Placeholder text to display in the input element.
+        icon (TagChildArg, optional): Icon to display with the input. Can be an HTML element or Tag object.
+        type (str, optional): Type of the input element (e.g., "text", "number", "password"). Defaults to "text".
+        semantic_class (str, optional): Additional classes to apply to the enclosing <div> element for styling.
+        semantic_label (str, optional): Label text to display above the input element.
+        semantic_label_class (str, optional): Additional classes to apply to the label element for styling.
+        **kwargs (TagAttrArg): includes all html attributes relevant to the input tag, including,
+        for example, `min`, `max` and `step` in case of input type = "number",
+        as well as `class_` that is passed directly to the input tag,
+        as opposed to the `semantic_class` that is passed to the enclosing div element.
+
+    Returns:
+        str: A string representing the generated HTML code.
+
+    Example:
+        input_with_icon = semantic_input(
+            id = "username",
+            placeholder = "Enter your username",
+            icon = tags.i(class_ = "user icon"),
+            semantic_label = "Username",
+            semantic_label_class = "blue",
+            required = True,
+        )
+        print(input_with_icon)
+
     """
     # Enclosing div's class
     if semantic_class is None:

shiny_semantic/elements/segment.py

@@ -10,6 +10,31 @@ def segment(
     class_: Optional[str] = None,
     **kwargs: TagAttrArg,
 ):
+    """
+    Generate a UI segment element in HTML.
+
+    This function creates a UI segment element, often used in web interfaces to visually
+    separate and group content. The segment can contain various child elements, such as text,
+    images, buttons, etc. It supports custom CSS classes and additional attributes.
+
+    Args:
+        *children (TagChildArg): Variable number of child elements to be included within the segment.
+        class_ (str, optional): Additional CSS class for the segment element.
+        **kwargs (TagAttrArg): Additional attributes to be added to the segment element.
+
+    Returns:
+        str: A string representing the generated segment element in HTML.
+
+    Example:
+        content = tags.p("This is the content of the segment.")
+        segment_element = segment(
+          content,
+          class_ = "custom-segment",
+          id = "segment-1"
+        )
+        print(segment_element)
+
+    """
     return tags.div(
         *children,
         class_=squash_whitespace(f"ui {class_ or ''} segment"),