Closed as not planned
Description
Issue
Every public module, class, method and attribute should have a docstring.
Requirements
- All docstrings should follow the Google Python Style Guide.
- Examples should use RST code-block format so that they render in the API reference correctly.
NOTE!
RST code block must have a newline between .. code-block:: python and the code example, and code example must be tabbed, to render correctly!
Examples
Module
langchain/foo/__init__.py
""""One line summary.
More detailed paragraph.
"""Class and attributes
Not Pydantic class
class Foo:
"""One line summary.
More detailed paragraph.
Attributes:
first_attr: does first thing.
second_attr: does second thing.
Example:
.. code-block:: python
from langchain.foo import Foo
f = Foo(1, 2, "bar")
...
"""
def __init__(self, a: int, b: int, c: str) -> None:
"""Initialize using a, b, c.
Args:
a: ...
b: ...
c: ...
"""
self.first_attr = a + b
self.second_attr = cNOTE
If the object attributes and init args are the same then you can just document the init args for non-Pydantic classes and just document the attributes for Pydantic classes.
Pydantic class
from typing import Any
from langchain_core.base_models import BaseModel
class FooPydantic(BaseModel):
"""One line summary.
More detailed paragraph.
Example:
.. code-block:: python
from langchain.foo import Foo
f = Foo(1, 2, "bar")
...
"""
first_attr: int
"""Does first thing."""
second_attr: str
"""Does second thing.
Additional info if needed.
"""
def __init__(self, a: int, b: int, c: str, **kwargs: Any) -> None:
"""Initialize using a, b, c.
Args:
a: ...
b: ...
c: ...
**kwargs: ...
"""
first_attr = a + b
second_attr = c
super().__init__(first_attr=first_attr, second_attr=second_attr, **kwargs)Function/method
def bar(a: int, b: str) -> float:
"""One line description.
More description if needed.
Args:
a: ...
b: ...
Returns:
A float of ...
Raises:
ValueError: If a is negative.
Example:
.. code-block:: python
from langchain.foo import bar
bar(1, "foo")
# -> 14.381
"""