doc string maxing

[fukurou]

In Python, docstrings can be used in methods just like functions, but they belong to a **class** and describe how the method works within that class.

### Example:
```python

class Calculator:
    """A simple calculator class."""


    def add(self, a, b):
        """
        Adds two numbers and returns the result.


        Parameters:
        a (int, float): First number.
        b (int, float): Second number.


        Returns:
        int, float: Sum of the numbers.
        """
        return a + b


# Accessing method docstring
print(Calculator.add.__doc__)

```

### Key Points:
1. **Methods are functions inside a class.** Docstrings work the same way, but they document the method **within a class context**.
2. **Use triple quotes (`"""`) at the beginning of the method.** This helps generate structured documentation.
3. **Docstrings can be retrieved using `.__doc__`.** This works for both classes and methods.

 

[fukurou]

How Docstrings Appear in PyCharm:​

1. Autocomplete Popup: When you type the name of a method and open parentheses (Calculator.add(), PyCharm may show a tooltip displaying the method signature along with its docstring.
2. Quick Documentation: Press Ctrl+Q (Windows/Linux) or F1 (Mac) while hovering over a method to see its docstring in a pop-up window.
3. Python Console: If you’re in PyCharm’s interactive Python console, using help(Class.method) or Class.method.__doc__ will display the docstring.

If autocomplete isn’t displaying docstrings, check that docstring support is enabled in PyCharm’s settings (Preferences > Editor > General > Code Completion).

 

[fukurou]

Docstrings are used to document Python methods, and when defining methods inside a class, they can also include **parameters** to explain what inputs a method expects.

### **1. Basic Docstring for a Method**
A method inside a class can have a docstring to describe what it does:

```python

class Car:
    """A simple class representing a car."""


    def start_engine(self):
        """Starts the engine of the car."""
        print("Engine started!")


# Accessing docstring
print(Car.start_engine.__doc__)

```

### **2. Adding Parameters to the Docstring**
When a method requires parameters, the docstring should include their names, types, and descriptions:

```python

class Car:
    """A simple class representing a car."""


    def set_speed(self, speed: int):
        """Sets the speed of the car.


        Args:
            speed (int): The speed to set, in kilometers per hour.
       
        Returns:
            str: A message confirming the speed change.
        """
        return f"Speed set to {speed} km/h"


# Accessing docstring
print(Car.set_speed.__doc__)

```

### **3. Using Different Docstring Formats**
There are **multiple ways** to format docstrings:
1. **Google Style** _(used in the example above)_.
2. **NumPy Style** _(used in scientific libraries)_.
3. **reStructuredText** _(used in Sphinx documentation tools)_.

#### **Example using NumPy-style docstrings:**
```python

class Car:
    """A simple class representing a car."""


    def accelerate(self, amount: float):
        """
        Increase the speed of the car.


        Parameters
        ----------
        amount : float
            The amount to increase the speed by, in km/h.


        Returns
        -------
        str
            A message confirming the speed increase.
        """
        return f"Speed increased by {amount} km/h"

```

### **4. Accessing Docstrings in PyCharm**
Since you're using **PyCharm**, you can:
- **Hover over the method** to see the docstring in a tooltip.
- **Use `Ctrl + Q` (Windows/Linux) or `F1` (Mac)** to view full documentation.
- **Call `help(Class.method)`** in the Python console to print the docstring.