# Docstrings

## Format

BDK docstrings adhere to [**Google style**](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) formatting:

* Docstrings are placed **immediately after** function, class, or method definitions.
* A brief **summary** that describes the functionality begins the docstring.
* The summary is followed by organized **sections**, separated by blank lines and labeled with headers.

In BDK projects, docstrings are applied to decorated methods and classes.

***

## Supported Sections

The following sections are supported in BDK docstrings, with alternative headers available for labeling flexibility.

### 1. Arguments and Parameters

Documents the arguments or parameters that a function or class accepts.

**Supported Headers**: `Args`, `Arguments`, `Parameters`, `Params`

**Example**

```python
@procedure("to add two numbers")
def add_numbers(a: int, b: int = 0) -> int:
    """
    Adds two numbers together.

    Args:
        a: The first number.
        b: The second number. Defaults to 0.
    """
    return a + b
```

### 2. Return Values

Documents the return value of a function or method.

**Supported Headers**: `Returns`

**Example**

```python
@procedure("to send an *SMS* message")
def send_sms_message(self, sender_number: str, recipient_number: str, message_body: str) -> Optional[str]:
    """
    Sends an SMS message using the Twilio API.

    Returns:
        The SID of the sent message if successful, otherwise None.
    """
```

### 3. Error Handling

Lists any exceptions or errors that a function might raise.

**Supported Headers**: `Raises`, `Exceptions`, `Except`

**Example**

```python
@timeout.setter
def timeout(self, timeout: float):
    """
    Sets the timeout value in milliseconds.

    Args:
        timeout (int): The timeout value to set. Must be a positive integer.

    Raises:
        ValueError: If the timeout value is less than or equal to 0.

    """
    if timeout <= 0:
        raise ValueError("timeout must be positive")
    self._timeout = timeout
```

### 4. Instance Attributes

List instance attributes in a class.

**Supported Headers**: `Attributes`

**Example**

```python
@concept(is_a="office user")
@dataclass
class OfficeUser:
    """
    An Office User represents a user in the Microsoft Graph. It includes key user details such as display name,
    email address, and job title.

    Attributes:
        id: The unique identifier for the user.
        display_name: The name displayed in the address book for the user.
        email_address: The user's email address (usually their user principal name).
        job_title: The user's job title.
    """

    id: str
    display_name: Optional[str] = None
    email_address: Optional[str] = None
    job_title: Optional[str] = None
```

### 5. Code Authors

Attributes the author(s) of the code.

**Supported Headers**: `Author`

**Example**

```python
@book(name="Sample Book")
class SampleBook:
    """
    A book shown as an example.

    Author:
      Kognitos
    """
```

### 6. Labels

Defines labeled data associated with a function related to [connections](https://docs.kognitos.com/legacy/legacy-experience/books/custom-books/api-reference/connections).

**Supported Headers**: `Labels`

**Example**

```python
@connect(noun_phrase="api keys")
def connect(self, api_key: str):
    """
    Authenticate to Open Weather API using the specified API key.

    Labels:
        api_key: API Key
    """
```

### 7. OAuth Labels

Describes OAuth labels for classes decorated with the [@oauth decorator](https://docs.kognitos.com/legacy/legacy-experience/books/custom-books/api-reference/decorators/oauth-decorator).

**Supported Headers**: `OAuth Labels`

**Example**

```python
@oauth(
    id="oauth",
    provider=OAuthProvider.MICROSOFT,
    flows=[OAuthFlow.AUTHORIZATION_CODE, OAuthFlow.CLIENT_CREDENTIALS],
    authorize_endpoint="https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/authorize",
    token_endpoint="https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/token",
    scopes=[
        "https://graph.microsoft.com/Files.ReadWrite",
        "https://graph.microsoft.com/Sites.Manage.All",
        "https://graph.microsoft.com/Sites.ReadWrite.All",
        "https://graph.microsoft.com/User.ReadWrite.All",
        "https://graph.microsoft.com/Directory.ReadWrite.All",
        "https://graph.microsoft.com/Group.ReadWrite.All",
        "https://graph.microsoft.com/GroupMember.ReadWrite.All",
        "https://graph.microsoft.com/Mail.ReadWrite",
        "https://graph.microsoft.com/Mail.ReadWrite.Shared",
        "https://graph.microsoft.com/Mail.Send",
        "https://graph.microsoft.com/Calendars.ReadWrite",
    ],
)
@book(name="MicrosoftBook")
class BaseMicrosoftBook:
    """
    Base class for all Microsoft Books.

    OAuth Arguments:
        TENANT_ID: The tenant ID of the Azure AD directory.

    OAuth Labels:
        TENANT_ID: Tenant ID
    """
```

### 8. OAuth Arguments

Describes OAuth arguments for classes decorated with the [@oauth decorator](https://docs.kognitos.com/legacy/legacy-experience/books/custom-books/api-reference/decorators/oauth-decorator).

**Supported Headers**: `OAuth Arguments`

**Example**

```python
@oauth(
    id="oauth",
    provider=OAuthProvider.MICROSOFT,
    flows=[OAuthFlow.AUTHORIZATION_CODE, OAuthFlow.CLIENT_CREDENTIALS],
    authorize_endpoint="https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/authorize",
    token_endpoint="https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/token",
    scopes=[
        "https://graph.microsoft.com/Files.ReadWrite",
        "https://graph.microsoft.com/Sites.Manage.All",
        "https://graph.microsoft.com/Sites.ReadWrite.All",
        "https://graph.microsoft.com/User.ReadWrite.All",
        "https://graph.microsoft.com/Directory.ReadWrite.All",
        "https://graph.microsoft.com/Group.ReadWrite.All",
        "https://graph.microsoft.com/GroupMember.ReadWrite.All",
        "https://graph.microsoft.com/Mail.ReadWrite",
        "https://graph.microsoft.com/Mail.ReadWrite.Shared",
        "https://graph.microsoft.com/Mail.Send",
        "https://graph.microsoft.com/Calendars.ReadWrite",
    ],
)
@book(name="MicrosoftBook")
class BaseMicrosoftBook:
    """
    Base class for all Microsoft Books.

    OAuth Arguments:
        TENANT_ID: The tenant ID of the Azure AD directory.

    OAuth Labels:
        TENANT_ID: Tenant ID
    """
```

### 9. Input Concepts

Describes the [**input concepts**](https://docs.kognitos.com/legacy/legacy-experience/books/custom-books/api-reference/concepts) for a procedure.

**Supported Headers**: `Input Concepts`

**Example**

```python
@procedure("to get the (current temperature) at a city")
def current_temperature(self, city: NounPhrase, unit: Optional[NounPhrase] = NounPhrase("metric")) -> float:
    """
    Fetch the current temperature for a specified city.

    Input Concepts:
        the city: The name of the city. Please refer to ISO 3166 for the state codes or country codes.
        the unit: Unit of measurement. standard, metric and imperial units are available. If you do
            not specify the units, metric units will be applied by default.
    """
```

### 10. Output Concepts

Describes the [**output concepts**](https://docs.kognitos.com/legacy/legacy-experience/books/custom-books/api-reference/concepts) for a procedure.

**Supported Headers**: `Output Concepts`

**Example**

```python
@procedure("to get the (current temperature) at a city")
def current_temperature(self, city: NounPhrase, unit: Optional[NounPhrase] = NounPhrase("metric")) -> float:
    """
    Fetch the current temperature for a specified city.

    Output Concepts:
        the current temperature: The current temperature in the specified units of measurement, or None if an error occurs.
    """
```

### 11. Examples

Outlines usage examples for a procedure.

**Supported Headers**: `Example`, `Examples`, `Example [1-5]`

**Example**

```python
@procedure("to get the (current temperature) at a city")
def current_temperature(self, city: NounPhrase, unit: Optional[NounPhrase] = NounPhrase("metric")) -> float:
    """
    Fetch the current temperature for a specified city.

    Example 1:
        Retrieve the current temperature at London

        >>> get the current temperature at London

    Example 2:
        Retrieve the current temperature at London in Celsius

        >>> get the current temperature at Buenos Aires with
        ...     the unit is metric
    """
```