[Feature] - Equity router descriptions & examples (#6103)

* feat: equity/calendar

* feat: compare router

* fix descriptions

* darkpool + discovery

* fix paragraph issues

* fix descriptions

* fundamental part 1

* fundamental part2

* transcipts

* ownership

* fix

* price

* shorts

* Update darkpool_router.py

* minor fix

* shorts examples

* examples

* ruff

* black

---------

Co-authored-by: Igor Radovanovic <74266147+IgorWounds@users.noreply.github.com>

31 files changed, 1476 insertions, 1350 deletions

diff --git a/openbb_platform/core/openbb_core/app/assets/parameter_pool.json b/openbb_platform/core/openbb_core/app/assets/parameter_pool.json
index a2d1f88c640..41b8af1d0f8 100644
--- a/openbb_platform/core/openbb_core/app/assets/parameter_pool.json
+++ b/openbb_platform/core/openbb_core/app/assets/parameter_pool.json
@@ -20,15 +20,6 @@
         "symbols": "AAPL,MSFT",
         "query": "AAPL"
     },
-    "equity.fundamental.historical_attributes": {
-        "tag": "ebitda"
-    },
-    "equity.fundamental.latest_attributes": {
-        "tag": "ceo"
-    },
-    "equity.fundamental.transcript": {
-        "year": 2020
-    },
     "etf": {
         "symbol": "SPY",
         "query": "Vanguard"
diff --git a/openbb_platform/core/openbb_core/app/static/package_builder.py b/openbb_platform/core/openbb_core/app/static/package_builder.py
index 3caa6d31974..4e7cd9b914e 100644
--- a/openbb_platform/core/openbb_core/app/static/package_builder.py
+++ b/openbb_platform/core/openbb_core/app/static/package_builder.py
@@ -830,17 +830,17 @@ class DocstringGenerator:
         available_providers = providers or "Optional[str]"
 
         obbject_description = (
-            "        OBBject\n"
-            f"            results : {results_type}\n"
-            "                Serializable results.\n"
-            f"            provider : {available_providers}\n"
-            "                Provider name.\n"
-            "            warnings : Optional[List[Warning_]]\n"
-            "                List of warnings.\n"
-            "            chart : Optional[Chart]\n"
-            "                Chart object.\n"
-            "            extra: Dict[str, Any]\n"
-            "                Extra info.\n"
+            "    OBBject\n"
+            f"        results : {results_type}\n"
+            "            Serializable results.\n"
+            f"        provider : {available_providers}\n"
+            "            Provider name.\n"
+            "        warnings : Optional[List[Warning_]]\n"
+            "            List of warnings.\n"
+            "        chart : Optional[Chart]\n"
+            "            Chart object.\n"
+            "        extra: Dict[str, Any]\n"
+            "            Extra info.\n"
         )
         obbject_description = obbject_description.replace("NoneType", "None")
 
@@ -871,22 +871,22 @@ class DocstringGenerator:
 
         def format_description(description: str) -> str:
             """Format description in docstrings."""
-            description = description.replace("\n", "\n        ")
+            description = description.replace("\n", "\n    ")
             return description
 
         standard_dict = params["standard"].__dataclass_fields__
         extra_dict = params["extra"].__dataclass_fields__
 
         if examples:
-            example_docstring = "\n        Example\n        -------\n"
-            example_docstring += "        >>> from openbb import obb\n"
+            example_docstring = "\n    Example\n    -------\n"
+            example_docstring += "    >>> from openbb import obb\n"
             for example in examples:
-                example_docstring += f"        >>> {example}\n"
+                example_docstring += f"    >>> {example}\n"
 
-        docstring = summary
+        docstring = summary.strip("\n")
         docstring += "\n\n"
-        docstring += "        Parameters\n"
-        docstring += "        ----------\n"
+        docstring += "    Parameters\n"
+        docstring += "    ----------\n"
 
         # Explicit parameters
         for param_name, param in explicit_params.items():
@@ -912,8 +912,8 @@ class DocstringGenerator:
                 description = ""
 
             type_str = format_type(type_, char_limit=79)  # type: ignore
-            docstring += f"        {param_name} : {type_str}\n"
-            docstring += f"            {format_description(description)}\n"
+            docstring += f"    {param_name} : {type_str}\n"
+            docstring += f"        {format_description(description)}\n"
 
         # Kwargs
         for param_name, param in extra_dict.items():
@@ -925,13 +925,13 @@ class DocstringGenerator:
 
             description = getattr(param.default, "description", "")
 
-            docstring += f"        {param_name} : {type_}\n"
-            docstring += f"            {format_description(description)}\n"
+            docstring += f"    {param_name} : {type_}\n"
+            docstring += f"        {format_description(description)}\n"
 
         # Returns
         docstring += "\n"
-        docstring += "        Returns\n"
-        docstring += "        -------\n"
+        docstring += "    Returns\n"
+        docstring += "    -------\n"
         provider_param = explicit_params.get("provider", None)
         available_providers = getattr(provider_param, "_annotation", None)
 
@@ -939,7 +939,7 @@ class DocstringGenerator:
 
         # Schema
         underline = "-" * len(model_name)
-        docstring += f"\n        {model_name}\n        {underline}\n"
+        docstring += f"\n    {model_name}\n    {underline}\n"
 
         for name, field in returns.items():
             try:
@@ -970,8 +970,8 @@ class DocstringGenerator:
 
             description = getattr(field, "description", "")
 
-            docstring += f"        {field.alias or name} : {field_type}\n"
-            docstring += f"            {format_description(description)}\n"
+            docstring += f"    {field.alias or name} : {field_type}\n"
+            docstring += f"        {format_description(description)}\n"
 
         if examples:
             docstring += example_docstring
diff --git a/openbb_platform/extensions/equity/openbb_equity/calendar/calendar_router.py b/openbb_platform/extensions/equity/openbb_equity/calendar/calendar_router.py
index 0c1e3ae2bf5..6693aecb202 100644
--- a/openbb_platform/extensions/equity/openbb_equity/calendar/calendar_router.py
+++ b/openbb_platform/extensions/equity/openbb_equity/calendar/calendar_router.py
@@ -15,45 +15,71 @@ router = Router(prefix="/calendar")
 # pylint: disable=unused-argument
 
 
-@router.command(model="CalendarIpo")
+@router.command(
+    model="CalendarIpo",
+    examples=[
+        "# Get all IPOs available.",
+        "obb.equity.calendar.ipo()",
+        "# Get IPOs for specific dates.",
+        "obb.equity.calendar.ipo(start_date='2024-02-01', end_date='2024-02-07')",
+    ],
+)
 async def ipo(
     cc: CommandContext,
     provider_choices: ProviderChoices,
     standard_params: StandardParams,
     extra_params: ExtraParams,
 ) -> OBBject:
-    """Upcoming and Historical IPO Calendar."""
+    """Get historical and upcoming initial public offerings (IPOs)."""
     return await OBBject.from_query(Query(**locals()))
 
 
-@router.command(model="CalendarDividend")
+@router.command(
+    model="CalendarDividend",
+    examples=[
+        "# Get dividend calendar for specific dates.",
+        "obb.equity.calendar.dividend(start_date='2024-02-01', end_date='2024-02-07')",
+    ],
+)
 async def dividend(
     cc: CommandContext,
     provider_choices: ProviderChoices,
     standard_params: StandardParams,
     extra_params: ExtraParams,
 ) -> OBBject:
-    """Upcoming and Historical Dividend Calendar."""
+    """Get historical and upcoming dividend payments. Includes dividend amount, ex-dividend and payment dates."""
     return await OBBject.from_query(Query(**locals()))
 
 
-@router.command(model="CalendarSplits")
+@router.command(
+    model="CalendarSplits",
+    examples=[
+        "# Get stock splits calendar for specific dates.",
+        "obb.equity.calendar.splits(start_date='2024-02-01', end_date='2024-02-07')",
+    ],
+)
 async def splits(
     cc: CommandContext,
     provider_choices: ProviderChoices,
     standard_params: StandardParams,
     extra_params: ExtraParams,
 ) -> OBBject:
-    """Calendar Splits. Show Stock Split Calendar."""
+    """Get historical and upcoming stock split operations."""
     return await OBBject.from_query(Query(**locals()))
 
 
-@router.command(model="CalendarEarnings")
+@router.command(
+    model="CalendarEarnings",
+    examples=[
+        "# Get earnings calendar for specific dates.",
+        "obb.equity.calendar.earnings(start_date='2024-02-01', end_date='2024-02-07')",
+    ],
+)
 async def earnings(
     cc: CommandContext,
     provider_choices: ProviderChoices,
     standard_params: StandardParams,
     extra_params: ExtraParams,
 ) -> OBBject:
-    """Upcoming and Historical earnings calendar."""
+    """Get historical and upcoming company earnings releases. Includes earnings per share (EPS) and revenue data."""
     return await OBBject.from_query(Query(**locals()))
diff --git a/openbb_platform/extensions/equity/openbb_equity/compare/compare_router.py b/openbb_platform/extensions/equity/openbb_equity/compare/compare_router.py
index 7ef48ef3642..da08a4cf110 100644
--- a/openbb_platform/extensions/equity/openbb_equity/compare/compare_router.py
+++ b/openbb_platform/extensions/equity/openbb_equity/compare/compare_router.py
@@ -21,16 +21,32 @@ async def peers(
     standard_params: StandardParams,
     extra_params: ExtraParams,
 ) -> OBBject:
-    """Equity Peers. Company peers."""
+    """Get the closest peers for a given company.
+
+    Peers consist of companies trading on the same exchange, operating within the same sector
+    and with comparable market capitalizations."""
     return await OBBject.from_query(Query(**locals()))
 
 
-@router.command(model="CompareGroups")
+@router.command(
+    model="CompareGroups",
+    examples=[
+        "# Group by sector and analyze valuation",
+        "obb.equity.compare.groups(group='sector', metric='valuation')",
+        "# Group by industry and analyze performance",
+        "obb.equity.compare.groups(group='industry', metric='performance')",
+        "# Group by country and analyze valuation",
+        "obb.equity.compare.groups(group='country', metric='valuation')",
+    ],
+)
 async def groups(
     cc: CommandContext,
     provider_choices: ProviderChoices,
     standard_params: StandardParams,
     extra_params: ExtraParams,
 ) -> OBBject:
-    """Compare Equity Sector and Industry Groups."""
+    """Get company data grouped by sector, industry or country and display either performance or valuation metrics.
+
+    Valuation metrics include price to earnings, price to book, price to sales ratios and price to cash flow.
+    Performance metrics include the stock price change for different time periods."""
     return await OBBject.from_query(Query(**locals()))
diff --git a/openbb_platform/extensions/equity/openbb_equity/darkpool/darkpool_router.py b/openbb_platform/extensions/equity/openbb_equity/darkpool/darkpool_router.py
index 5c5b59ee626..1cda9b50ec5 100644
--- a/openbb_platform/extensions/equity/openbb_equity/darkpool/darkpool_router.py
+++ b/openbb_platform/extensions/equity/openbb_equity/darkpool/darkpool_router.py
@@ -15,16 +15,21 @@ router = Router(prefix="/darkpool")
 # pylint: disable=unused-argument
 
 
-@router.command(model="OTCAggregate")
+@router.command(
+    model="OTCAggregate",
+    examples=[
+        "# Get OTC data for a symbol",
+        "obb.equity.darkpool.otc(symbol='AAPL')",
+    ],
+)
 async def otc(
     cc: CommandContext,
     provider_choices: ProviderChoices,
     standard_params: StandardParams,
     extra_params: ExtraParams,
 ) -> OBBject:
-    """Weekly aggregate trade data for Over The Counter deals.
+    """Get the weekly aggregate trade data for Over The Counter deals.
 
     ATS and non-ATS trading data for each ATS/firm
-    with trade reporting obligations under FINRA rules.
-    """
+    with trade reporting obligations under FINRA rules."""
     return await OBBject.from_query(Query(**locals()))
diff --git a/openbb_platform/extensions/equity/openbb_equity/discovery/discovery_router.py b/openbb_platform/extensions/equity/openbb_equity/discovery/discovery_router.py
index f153c982a37..58247da48c8 100644
--- a/openbb_platform/extensions/equity/openbb_equity/discovery/discovery_router.py
+++ b/openbb_platform/extensions/equity/openbb_equity/discovery/discovery_router.py
@@ -21,7 +21,7 @@ async def gainers(
     standard_params: StandardParams,
     extra_params: ExtraParams,
 ) -> OBBject:
-    """Get the top Equity gainers."""
+    """Get the top price gainers in the stock market."""
     return await OBBject.from_query(Query(**locals()))
 
 
@@ -32,7 +32,7 @@ async def losers(
     standard_params: StandardParams,
     extra_params: ExtraParams,
 ) -> OBBject:
-    """Get the top Equity losers."""
+    """Get the top price losers in the stock market."""
     return await OBBject.from_query(Query(**locals()))
 
 
@@ -43,7 +43,7 @@ async def active(
     standard_params: StandardParams,
     extra_params: ExtraParams,
 ) -> OBBject:
-    """Get the most active Equities."""
+    """Get the most actively traded stocks based on volume."""
     return await OBBject.from_query(Query(**locals()))
 
 
@@ -54,7 +54,7 @@ async def undervalued_large_caps(
     standard_params: StandardParams,
     extra_params: ExtraParams,
 ) -> OBBject:
-    """Get undervalued large cap Equities."""
+    """Get potentially undervalued large cap stocks."""
     return await OBBject.from_query(Query(**locals()))
 
 
@@ -65,7 +65,7 @@ async def undervalued_growth(
     standard_params: StandardParams,
     extra_params: ExtraParams,
 ) -> OBBject:
-    """Get undervalued growth Equities."""
+    """Get potentially undervalued growth stocks."""
     return await OBBject.from_query(Query(**locals()))
 
 
@@ -76,7 +76,7 @@ async def aggressive_small_caps(
     standard_params: StandardParams,
     extra_params: ExtraParams,
 ) -> OBBject:
-    """Get aggressive small cap Equities."""
+    """Get top small cap stocks based on earnings growth."""
     return await OBBject.from_query(Query(**locals()))
 
 
@@ -87,7 +87,7 @@ async def growth_tech(
     standard_params: StandardParams,
     extra_params: ExtraParams,
 ) -> OBBject:
-    """Get growth tech Equities."""
+    """Get top tech stocks based on revenue and earnings growth."""
     return await OBBject.from_query(Query(**locals()))
 
 
@@ -101,8 +101,7 @@ async def top_retail(
     """Tracks over $30B USD/day of individual investors trades.
 
     It gives a daily view into retail activity and sentiment for over 9,500 US traded stocks,
-    ADRs, and ETPs.
-    """
+    ADRs, and ETPs."""
     return await OBBject.from_query(Query(**locals()))
 
 
@@ -113,16 +112,27 @@ async def upcoming_release_days(
     standard_params: StandardParams,
     extra_params: ExtraParams,
 ) -> OBBject:
-    """Get upcoming release days."""
+    """Get upcoming earnings release dates."""
     return await OBBject.from_query(Query(**locals()))
 
 
-@router.command(model="DiscoveryFilings")
+@router.command(
+    model="DiscoveryFilings",
+    examples=[
+        "# Get filings for the year 2023, limited to 100 results",
+        "obb.equity.discovery.filings(start_date='2023-01-01', end_date='2023-12-31')",
+    ],
+)
 async def filings(
     cc: CommandContext,
     provider_choices: ProviderChoices,
     standard_params: StandardParams,
     extra_params: ExtraParams,
 ) -> OBBject:
-    """Get the most-recent filings submitted to the SEC."""
+    """Get the URLs to SEC filings reported to EDGAR database, such as 10-K, 10-Q, 8-K, and more. SEC
+    filings include Form 10-K, Form 10-Q, Form 8-K, the proxy statement, Forms 3, 4, and 5, Schedule 13, Form 114,
+    Foreign Investment Disclosures and others. The annual 10-K report is required to be
+    filed annually and includes the company's financial statements, management discussion and analysis,
+    and audited financial statements.
+    """
     return await OBBject.from_query(Query(**locals()))
diff --git a/openbb_platform/extensions/equity/openbb_equity/equity_router.py b/openbb_platform/extensions/equity/openbb_equity/equity_router.py
index 8117a013a45..d47e2e5dcd4 100644
--- a/openbb_platform/extensions/equity/openbb_equity/equity_router.py
+++ b/openbb_platform/extensions/equity/openbb_equity/equity_router.py
@@ -41,7 +41,7 @@ async def search(
     standard_params: StandardParams,
     extra_params: ExtraParams,
 ) -> OBBject:
-    """Equity Search. Search for a company or stock ticker."""
+    """Search for stock symbol, CIK, LEI, or company name."""
     return await OBBject.from_query(Query(**locals()))
 
 
@@ -52,7 +52,8 @@ async def screener(
     standard_params: StandardParams,
     extra_params: ExtraParams,
 ) -> OBBject:
-    """Equity Screen. Screen for companies meeting various criteria."""
+    """Screen for companies meeting various criteria. These criteria include
+    market cap, price, beta, volume, and dividend yield."""
     return await OBBject.from_query(Query(**locals()))
 
 
@@ -63,7 +64,7 @@ async def profile(
     standard_params: StandardParams,
     extra_params: ExtraParams,
 ) -> OBBject:
-    """Equity Info. Get general price and performance metrics of a stock."""
+    """Get general information about a company. This includes company name, industry, sector and price data."""
     return await OBBject.from_query(Query(**locals()))
 
 
@@ -74,5 +75,5 @@ async def market_snapshots(
     standard_params: StandardParams,
     extra_params: ExtraParams,
 ) -> OBBject:
-    """Get a current, complete, market snapshot."""
+    """Get an updated equity market snapshot. This includes price data for thousands of stocks."""
     return await OBBject.from_query(Query(**locals()))
diff --git a/openbb_platform/extensions/equity/openbb_equity/estimates/estimates_router.py b/openbb_platform/extensions/equity/openbb_equity/estimates/estimates_router.py
index b1fff34159f..4d6f8902fe6 100644
--- a/openbb_platform/extensions/equity/openbb_equity/estimates/estimates_router.py
+++ b/openbb_platform/extensions/equity/openbb_equity/estimates/estimates_router.py
@@ -28,7 +28,7 @@ async def price_target(
     standard_params: StandardParams,
     extra_params: ExtraParams,
 ) -> OBBject:
-    """Analyst price targets by company."""
+    """Get analyst price targets by company."""
     return await OBBject.from_query(Query(**locals()))
 
 
@@ -45,7 +45,7 @@ async def historical(
     standard_params: StandardParams,
     extra_params: ExtraParams,
 ) -> OBBject:
-    """Historical analyst estimates for earnings and revenue."""
+    """Get historical analyst estimates for earnings and revenue."""
     return await OBBject.from_query(Query(**locals()))
 
 
@@ -62,7 +62,7 @@ async def consensus(
     standard_params: StandardParams,
     extra_params: ExtraParams,
 ) -> OBBject:
-    """Consensus price target and recommendation."""
+    """Get consensus price target and recommendation."""
     return await OBBject.from_query(Query(**locals()))
 
 
diff --git a/openbb_platform/extensions/equity/openbb_equity/fundamental/fundamental_router.py b/openbb_platform/extensions/equity/openbb_equity/fundamental/fundamental_router.py
index a61577c7193..eb36250b484 100644
--- a/openbb_platform/extensions/equity/openbb_equity/fundamental/fundamental_router.py
+++ b/openbb_platform/extensions/equity/openbb_equity/fundamental/fundamental_router.py
@@ -22,7 +22,7 @@ async def multiples(
     standard_params: StandardParams,
     extra_params: ExtraParams,
 ) -> OBBject:
-    """Equity Valuation Multiples. Valuation multiples for a stock ticker."""
+    """Get equity valuation multiples for a given company."""
     return aw