docstring-generator-ext 2.0.2__tar.gz → 2.0.3__tar.gz

{docstring_generator_ext-2.0.2 → docstring_generator_ext-2.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstring_generator_ext
-Version: 2.0.2
+Version: 2.0.3
 Summary: Generate Docstrings with type-hint information.
 Author-email: FelixTheC <fberndt87@gmail.com>
 Classifier: Environment :: Console
@@ -25,13 +25,20 @@ Requires-Dist: pybind11>=3.0.4
 ## Features
 
 - **Automatic Docstring Injection**: Parses Python files and inserts docstrings for functions and methods.
+- **Async-function support**: Handles both `def` and `async def` functions transparently.
 - **Type-Hint Awareness**: Extracts type information from annotations and default values.
 - **Multiple Styles**: Supports popular docstring formats:
   - **reST** (reStructuredText)
   - **Google** style
   - **NumPy** style
+- **Format-style detection**: Automatically detects the style of an existing docstring and refuses to silently mix styles unless `allow_overwrite=True` is passed.
+- **Style conversion**: With `allow_overwrite=True`, converts a docstring written in one style to another in a single call.
+- **Exception detection**: Analyses the function body with Python's `ast` module to identify raised exceptions and include them in the docstring.
+- **Docstring coverage auditing**: `check_docstring()` reports how many functions in a file have complete, partial, or missing docstrings without modifying the file.
 - **High Performance**: Core logic implemented in C++ for fast processing.
-- **Preserves Existing Content**: Can update existing docstrings while trying to preserve manually added descriptions (using a special `$` marker convention).
+- **Preserves Existing Content**: Keeps manually written descriptions across re-runs using special in-docstring markers:
+  - `$N` binds the text on that line to the *N*-th function parameter.
+  - `>>` provides the return-value description.
 
 ## Installation
 
@@ -81,7 +88,23 @@ style = docstring_generator_ext.DocstringFormatStyle.GOOGLE
 docstring_generator_ext.parse_file(file_path, style)
 ```
 
-You can also audit an existing file to see how well its functions are documented, without making any changes:
+### Overwriting an existing docstring format
+
+By default, `parse_file` refuses to overwrite a docstring that was already written in a **different** style than the one you requested, and will print a warning instead. Pass `allow_overwrite=True` to let the extension convert the existing docstring to the new style:
+
+```python
+import docstring_generator_ext
+
+file_path = "path/to/your_script.py"
+style = docstring_generator_ext.DocstringFormatStyle.NUMPY
+
+# Convert any existing docstring style to NUMPY — previous style will be removed
+docstring_generator_ext.parse_file(file_path, style, allow_overwrite=True)
+```
+
+### Auditing docstring coverage
+
+You can audit an existing file to see how well its functions are documented, without making any changes:
 
 ```python
 import docstring_generator_ext
@@ -115,6 +138,64 @@ The extension provides an enum `DocstringFormatStyle` to choose the desired outp
 - `docstring_generator_ext.DocstringFormatStyle.GOOGLE`
 - `docstring_generator_ext.DocstringFormatStyle.NUMPY`
 
+### Preserving descriptions with special markers
+
+When the extension processes a file that already contains docstrings, it tries to keep manually written descriptions in place. Two marker conventions are supported:
+
+#### `$N` — argument description markers
+
+Place a `$` followed by the **1-based index** of the parameter inside the docstring to bind a free-form description to that argument. The marker and the text on its line are extracted and attached to the corresponding parameter; the `$N` line is then removed from the generated docstring.
+
+```python
+def add(a: int, b: int) -> int:
+    """Add two numbers together.
+
+    $1 The first operand.
+    $2 The second operand.
+    """
+    return a + b
+```
+
+After the next `parse_file` run the descriptions will be wired to `a` and `b` automatically.
+
+```python
+def add(a: int, b: int) -> int:
+    """Add two numbers together.
+
+    Args:
+        a (int): The first operand.
+        b (int): The second operand.
+    Returns:
+        int
+    """
+    return a + b
+```
+
+#### `>>` — return description marker
+
+Place `>>` on its own line inside the docstring to provide the description for the return value. The text after `>>` on that line is extracted as the return description, and the marker line is removed.
+
+```python
+def square(x: int) -> int:
+    """Square a number.
+
+    >> The squared value of x.
+    """
+    return x * x
+```
+After the next `parse_file` run the descriptions will be wired to `Returns` description automatically.
+```python
+def square(x: int) -> int:
+    """Square a number.
+
+    Args:
+        x (int):
+    Returns:
+        int: The squared value of x.
+    """
+    return x * x
+```
+
 ## C++20
 
 The core of this extension is written in **C++20** to take full advantage of the modern standard's best algorithms and features:

{docstring_generator_ext-2.0.2 → docstring_generator_ext-2.0.3}/README.md

@@ -11,13 +11,20 @@
 ## Features
 
 - **Automatic Docstring Injection**: Parses Python files and inserts docstrings for functions and methods.
+- **Async-function support**: Handles both `def` and `async def` functions transparently.
 - **Type-Hint Awareness**: Extracts type information from annotations and default values.
 - **Multiple Styles**: Supports popular docstring formats:
   - **reST** (reStructuredText)
   - **Google** style
   - **NumPy** style
+- **Format-style detection**: Automatically detects the style of an existing docstring and refuses to silently mix styles unless `allow_overwrite=True` is passed.
+- **Style conversion**: With `allow_overwrite=True`, converts a docstring written in one style to another in a single call.
+- **Exception detection**: Analyses the function body with Python's `ast` module to identify raised exceptions and include them in the docstring.
+- **Docstring coverage auditing**: `check_docstring()` reports how many functions in a file have complete, partial, or missing docstrings without modifying the file.
 - **High Performance**: Core logic implemented in C++ for fast processing.
-- **Preserves Existing Content**: Can update existing docstrings while trying to preserve manually added descriptions (using a special `$` marker convention).
+- **Preserves Existing Content**: Keeps manually written descriptions across re-runs using special in-docstring markers:
+  - `$N` binds the text on that line to the *N*-th function parameter.
+  - `>>` provides the return-value description.
 
 ## Installation
 
@@ -67,7 +74,23 @@ style = docstring_generator_ext.DocstringFormatStyle.GOOGLE
 docstring_generator_ext.parse_file(file_path, style)
 ```
 
-You can also audit an existing file to see how well its functions are documented, without making any changes:
+### Overwriting an existing docstring format
+
+By default, `parse_file` refuses to overwrite a docstring that was already written in a **different** style than the one you requested, and will print a warning instead. Pass `allow_overwrite=True` to let the extension convert the existing docstring to the new style:
+
+```python
+import docstring_generator_ext
+
+file_path = "path/to/your_script.py"
+style = docstring_generator_ext.DocstringFormatStyle.NUMPY
+
+# Convert any existing docstring style to NUMPY — previous style will be removed
+docstring_generator_ext.parse_file(file_path, style, allow_overwrite=True)
+```
+
+### Auditing docstring coverage
+
+You can audit an existing file to see how well its functions are documented, without making any changes:
 
 ```python
 import docstring_generator_ext
@@ -101,6 +124,64 @@ The extension provides an enum `DocstringFormatStyle` to choose the desired outp
 - `docstring_generator_ext.DocstringFormatStyle.GOOGLE`
 - `docstring_generator_ext.DocstringFormatStyle.NUMPY`
 
+### Preserving descriptions with special markers
+
+When the extension processes a file that already contains docstrings, it tries to keep manually written descriptions in place. Two marker conventions are supported:
+
+#### `$N` — argument description markers
+
+Place a `$` followed by the **1-based index** of the parameter inside the docstring to bind a free-form description to that argument. The marker and the text on its line are extracted and attached to the corresponding parameter; the `$N` line is then removed from the generated docstring.
+
+```python
+def add(a: int, b: int) -> int:
+    """Add two numbers together.
+
+    $1 The first operand.
+    $2 The second operand.
+    """
+    return a + b
+```
+
+After the next `parse_file` run the descriptions will be wired to `a` and `b` automatically.
+
+```python
+def add(a: int, b: int) -> int:
+    """Add two numbers together.
+
+    Args:
+        a (int): The first operand.
+        b (int): The second operand.
+    Returns:
+        int
+    """
+    return a + b
+```
+
+#### `>>` — return description marker
+
+Place `>>` on its own line inside the docstring to provide the description for the return value. The text after `>>` on that line is extracted as the return description, and the marker line is removed.
+
+```python
+def square(x: int) -> int:
+    """Square a number.
+
+    >> The squared value of x.
+    """
+    return x * x
+```
+After the next `parse_file` run the descriptions will be wired to `Returns` description automatically.
+```python
+def square(x: int) -> int:
+    """Square a number.
+
+    Args:
+        x (int):
+    Returns:
+        int: The squared value of x.
+    """
+    return x * x
+```
+
 ## C++20
 
 The core of this extension is written in **C++20** to take full advantage of the modern standard's best algorithms and features:

{docstring_generator_ext-2.0.2 → docstring_generator_ext-2.0.3}/docstring_generator_ext.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstring_generator_ext
-Version: 2.0.2
+Version: 2.0.3
 Summary: Generate Docstrings with type-hint information.
 Author-email: FelixTheC <fberndt87@gmail.com>
 Classifier: Environment :: Console
@@ -25,13 +25,20 @@ Requires-Dist: pybind11>=3.0.4
 ## Features
 
 - **Automatic Docstring Injection**: Parses Python files and inserts docstrings for functions and methods.
+- **Async-function support**: Handles both `def` and `async def` functions transparently.
 - **Type-Hint Awareness**: Extracts type information from annotations and default values.
 - **Multiple Styles**: Supports popular docstring formats:
   - **reST** (reStructuredText)
   - **Google** style
   - **NumPy** style
+- **Format-style detection**: Automatically detects the style of an existing docstring and refuses to silently mix styles unless `allow_overwrite=True` is passed.
+- **Style conversion**: With `allow_overwrite=True`, converts a docstring written in one style to another in a single call.
+- **Exception detection**: Analyses the function body with Python's `ast` module to identify raised exceptions and include them in the docstring.
+- **Docstring coverage auditing**: `check_docstring()` reports how many functions in a file have complete, partial, or missing docstrings without modifying the file.
 - **High Performance**: Core logic implemented in C++ for fast processing.
-- **Preserves Existing Content**: Can update existing docstrings while trying to preserve manually added descriptions (using a special `$` marker convention).
+- **Preserves Existing Content**: Keeps manually written descriptions across re-runs using special in-docstring markers:
+  - `$N` binds the text on that line to the *N*-th function parameter.
+  - `>>` provides the return-value description.
 
 ## Installation
 
@@ -81,7 +88,23 @@ style = docstring_generator_ext.DocstringFormatStyle.GOOGLE
 docstring_generator_ext.parse_file(file_path, style)
 ```
 
-You can also audit an existing file to see how well its functions are documented, without making any changes:
+### Overwriting an existing docstring format
+
+By default, `parse_file` refuses to overwrite a docstring that was already written in a **different** style than the one you requested, and will print a warning instead. Pass `allow_overwrite=True` to let the extension convert the existing docstring to the new style:
+
+```python
+import docstring_generator_ext
+
+file_path = "path/to/your_script.py"
+style = docstring_generator_ext.DocstringFormatStyle.NUMPY
+
+# Convert any existing docstring style to NUMPY — previous style will be removed
+docstring_generator_ext.parse_file(file_path, style, allow_overwrite=True)
+```
+
+### Auditing docstring coverage
+
+You can audit an existing file to see how well its functions are documented, without making any changes:
 
 ```python
 import docstring_generator_ext
@@ -115,6 +138,64 @@ The extension provides an enum `DocstringFormatStyle` to choose the desired outp
 - `docstring_generator_ext.DocstringFormatStyle.GOOGLE`
 - `docstring_generator_ext.DocstringFormatStyle.NUMPY`
 
+### Preserving descriptions with special markers
+
+When the extension processes a file that already contains docstrings, it tries to keep manually written descriptions in place. Two marker conventions are supported:
+
+#### `$N` — argument description markers
+
+Place a `$` followed by the **1-based index** of the parameter inside the docstring to bind a free-form description to that argument. The marker and the text on its line are extracted and attached to the corresponding parameter; the `$N` line is then removed from the generated docstring.
+
+```python
+def add(a: int, b: int) -> int:
+    """Add two numbers together.
+
+    $1 The first operand.
+    $2 The second operand.
+    """
+    return a + b
+```
+
+After the next `parse_file` run the descriptions will be wired to `a` and `b` automatically.
+
+```python
+def add(a: int, b: int) -> int:
+    """Add two numbers together.
+
+    Args:
+        a (int): The first operand.
+        b (int): The second operand.
+    Returns:
+        int
+    """
+    return a + b
+```
+
+#### `>>` — return description marker
+
+Place `>>` on its own line inside the docstring to provide the description for the return value. The text after `>>` on that line is extracted as the return description, and the marker line is removed.
+
+```python
+def square(x: int) -> int:
+    """Square a number.
+
+    >> The squared value of x.
+    """
+    return x * x
+```
+After the next `parse_file` run the descriptions will be wired to `Returns` description automatically.
+```python
+def square(x: int) -> int:
+    """Square a number.
+
+    Args:
+        x (int):
+    Returns:
+        int: The squared value of x.
+    """
+    return x * x
+```
+
 ## C++20
 
 The core of this extension is written in **C++20** to take full advantage of the modern standard's best algorithms and features:

{docstring_generator_ext-2.0.2 → docstring_generator_ext-2.0.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docstring_generator_ext"
-version = "2.0.2"
+version = "2.0.3"
 description = "Generate Docstrings with type-hint information."
 authors = [
     { name = "FelixTheC", email = "fberndt87@gmail.com" },

{docstring_generator_ext-2.0.2 → docstring_generator_ext-2.0.3}/src/FunctionFormat.cpp

@@ -152,6 +152,70 @@ void FunctionInfo::update_descriptions(const DocstringFormatStyle &formatStyle)
     }
 }
 
+void FunctionDocstring::detect_format_style() noexcept {
+    bool could_be_numpy = false;
+    bool could_be_google = false;
+    bool could_be_rest = false;
+
+    could_be_google = std::ranges::any_of(TypicalFormatStyle[1].second, [this](const auto &part) {
+        return docstring.find(part) != std::string::npos;
+    });
+
+    // Numpy uses `Returns` as the keyword for the return value description and Google uses `Returns:` as the keyword for the return value description
+    // so if it's not google, it could be numpy
+    if (!could_be_google)
+        could_be_numpy = std::ranges::any_of(TypicalFormatStyle[0].second, [this](const auto &part) {
+            return docstring.find(part) != std::string::npos;
+        });
+
+    could_be_rest = std::ranges::any_of(TypicalFormatStyle[2].second, [this](const auto &part) {
+        return docstring.find(part) != std::string::npos;
+    });
+
+    const int total = could_be_numpy + could_be_google + could_be_rest;
+
+    // this means we have multiple format styles in the docstring which should be avoided
+    // so we should not detect the format style
+    if (total > 1) {
+        detected_format_style = std::nullopt;
+        return;
+    }
+
+    if (could_be_numpy) {
+        detected_format_style = DocstringFormatStyle::NUMPY;
+    } else if (could_be_google) {
+        detected_format_style = DocstringFormatStyle::GOOGLE;
+    } else if (could_be_rest) {
+        detected_format_style = DocstringFormatStyle::reST;
+    }
+}
+
+[[nodiscard]] int FunctionDocstring::remove_old_format_style() noexcept {
+    if (!detected_format_style.has_value())
+        return -1;
+
+    const auto get_end_pos = [](std::string& _docstring, StyleSections sections) {
+        std::vector<size_t> res;
+        std::ranges::for_each(sections, [&](const auto& line) {
+                res.emplace_back(_docstring.find(line));
+            });
+        std::ranges::sort(res, std::less<>());
+        return res[0];
+    };
+
+    switch (*detected_format_style)
+    {
+    case DocstringFormatStyle::NUMPY:
+        return get_end_pos(docstring, TypicalFormatStyle[0].second);
+    case DocstringFormatStyle::GOOGLE:
+        return get_end_pos(docstring, TypicalFormatStyle[1].second);
+    case DocstringFormatStyle::reST:
+        return get_end_pos(docstring, TypicalFormatStyle[2].second);
+    }
+
+    return -1;
+}
+
 FunctionDocstring get_docstring(const py::object &obj, const py::module &ast_module) noexcept {
     FunctionDocstring functionDocstring{};
 

{docstring_generator_ext-2.0.2 → docstring_generator_ext-2.0.3}/src/FunctionFormat.hpp

@@ -1,5 +1,7 @@
 #ifndef DOCSTRING_GENERATOR_EXT_FUNCTIONFORMAT_HPP
 #define DOCSTRING_GENERATOR_EXT_FUNCTIONFORMAT_HPP
+
+#include <map>
 #include <set>
 #include <string>
 #include <vector>
@@ -21,6 +23,13 @@ enum class DocstringFormatStyle {
     NUMPY
 };
 
+using StyleSections = std::array<std::string_view, 3>;
+constexpr std::array<std::pair<std::string_view, StyleSections>, 3> TypicalFormatStyle = {{
+    {"numpy",  {"Parameters\n", "Returns\n", "Raises\n"}},
+    {"google", {"Args:", "Returns:", "Raises:"}},
+    {"rest",   {":param", ":returns:", ":raises"}}
+}};
+
 ParameterKind from_str(const std::string &kind);
 std::ostream &operator<<(std::ostream &out, ParameterKind const &obj) noexcept;
 
@@ -47,6 +56,10 @@ struct FunctionDocstring {
     uint32_t start_line{};
     size_t end_line{};
     std::string docstring;
+    std::optional<DocstringFormatStyle> detected_format_style {std::nullopt};
+
+    void detect_format_style() noexcept;
+    [[nodiscard]] int remove_old_format_style() noexcept;
 };
 
 FunctionDocstring get_docstring(const py::object &obj, const py::module &ast_module) noexcept;

{docstring_generator_ext-2.0.2 → docstring_generator_ext-2.0.3}/src/GoogleDocstring.cpp

@@ -17,6 +17,21 @@ void GoogleDocstring::check_current_docstring() noexcept {
     }
 }
 
+std::string GoogleDocstring::cleanArgsDescription(const std::string &arg, const std::string &description) noexcept {
+    std::string res = std::string {description};
+
+    if (const auto startPos = description.find("Args:\n"); startPos < std::string::npos) {
+        res = res.substr(startPos, res.size() - startPos);
+    }
+
+    if (const auto startPos = res.find(arg); startPos < std::string::npos) {
+        const auto pos = startPos + arg.size() + 1;
+        res = res.substr(pos, res.size() - pos);
+    }
+
+    return res;
+}
+
 std::string GoogleDocstring::docstringArgs() noexcept {
     auto current_py_tab = get_tabs();
 
@@ -56,7 +71,7 @@ std::string GoogleDocstring::docstringArgs() noexcept {
         }
         if (!val.description.empty()) {
             result += ": ";
-            result += val.description;
+            result += cleanArgsDescription(val.name, val.description);
         }
         if (!val.default_value.empty()) {
             result += " (default is ";
@@ -79,15 +94,10 @@ std::string GoogleDocstring::docstringReturn() noexcept {
 
     if (!functionInfo.returns.description.empty() || !functionInfo.returns.type.empty()) {
         result += "\n";
-
-        if (PY_TAB != current_py_tab) {
-            result += PY_TAB;
-        } else {
-            result += PY_TAB;
-            current_py_tab = PY_TAB + PY_TAB;
-        }
+        result += current_py_tab;
 
         result += "Returns:\n";
+        current_py_tab += PY_TAB;
         result += current_py_tab;
 
         if (!functionInfo.returns.type.empty()) {
@@ -112,13 +122,9 @@ std::string GoogleDocstring::docstringExceptions() noexcept {
     auto current_py_tab = get_tabs();
 
     result += "\n";
+    result += current_py_tab;
 
-    if (PY_TAB != current_py_tab) {
-        result += PY_TAB;
-    } else {
-        result += PY_TAB;
-        current_py_tab = PY_TAB + PY_TAB;
-    }
+    current_py_tab += PY_TAB;
 
     result += "Raises:\n";
     result += current_py_tab;

{docstring_generator_ext-2.0.2 → docstring_generator_ext-2.0.3}/src/GoogleDocstring.hpp

@@ -8,6 +8,7 @@ struct GoogleDocstring : DocstringFormat {
     std::string docstringArgs() noexcept override;
     std::string docstringReturn() noexcept override;
     std::string docstringExceptions() noexcept override;
+    std::string cleanArgsDescription(const std::string &arg, const std::string &description) noexcept;
 };
 
 

{docstring_generator_ext-2.0.2 → docstring_generator_ext-2.0.3}/src/IDocstringFormat.cpp

@@ -1,6 +1,5 @@
 #include "IDocstringFormat.hpp"
 #include "parser.hpp"
-#include <sstream>
 
 [[ nodiscard ]] std::string DocstringFormat::docstring() noexcept {
     std::string result;

{docstring_generator_ext-2.0.2 → docstring_generator_ext-2.0.3}/src/docstringFormat.cpp

@@ -1,6 +1,5 @@
 #include "docstringFormat.hpp"
 #include <algorithm>
-#include <format>
 #include <fstream>
 #include <iostream>
 #include <sstream>
@@ -17,13 +16,14 @@
 
 namespace py = pybind11;
 
-void write_to_file_position(
+[[nodiscard]] WriteResult write_to_file_position(
     std::vector<FunctionInfo> &&infos,
     const std::string &file_path,
-    const DocstringFormatStyle &formatStyle
+    const DocstringFormatStyle &formatStyle,
+    const bool &allow_overwrite
 ) noexcept;
 
-std::string read_file(const std::string &file_path) {
+std::optional<std::string>  read_file(const std::string &file_path) {
     std::ifstream file(file_path, std::ios::binary);
     std::string file_content{};
 
@@ -32,19 +32,18 @@ std::string read_file(const std::string &file_path) {
         outsstream << file.rdbuf();
         file_content = outsstream.str();
     } else {
-        throw py::value_error(file_path + " is not a valid path.");
+        return std::nullopt;
     }
 
     return file_content;
 }
 
-void parse_file(std::string &file_path, DocstringFormatStyle &formatStyle) {
+std::vector<FunctionInfo> createFunctionInfos(const std::string &text, const DocstringFormatStyle &formatStyle) {
+    std::vector<FunctionInfo> infos{};
     py::module ast_module = py::module_::import("ast");
-    py::object generator_result = ast_module.attr("walk")(ast_module.attr("parse")(read_file(file_path)));
+    const py::object generator_result = ast_module.attr("walk")(ast_module.attr("parse")(text));
     py::iterator iter = py::iter(generator_result);
 
-    std::vector<FunctionInfo> infos{};
-
     for (auto &obj: iter) {
         if (py::isinstance(obj, ast_module.attr("FunctionDef")) || py::isinstance(
                 obj,
@@ -53,9 +52,20 @@ void parse_file(std::string &file_path, DocstringFormatStyle &formatStyle) {
             FunctionInfo function_info = analyze_function(obj, ast_module);
             function_info.update_descriptions(formatStyle);
             infos.emplace_back(function_info);
-        }
+            }
+    }
+
+    return infos;
+}
+
+void parse_file(const std::string &file_path, const DocstringFormatStyle &formatStyle, const bool &allow_overwrite) {
+    const auto result = read_file(file_path);
+    if (!result.has_value()) {
+        throw py::value_error(file_path + " is not a valid path.");
     }
 
+    std::vector<FunctionInfo> infos = createFunctionInfos(*result, formatStyle);
+
     std::ranges::sort(
         infos,
         [](const FunctionInfo &left, const FunctionInfo &right) {
@@ -64,7 +74,21 @@ void parse_file(std::string &file_path, DocstringFormatStyle &formatStyle) {
     );
 
 #ifndef DRY_RUN
-    write_to_file_position(std::move(infos), file_path, formatStyle);
+    const auto res = write_to_file_position(std::move(infos), file_path, formatStyle, allow_overwrite);
+    switch (res) {
+
+    case SUCCESS:
+      break;
+    case FAILURE:
+        py::print("Could not write to file.");
+      break;
+    case FILE_NOT_FOUND:
+        py::print("Could not write to file.");
+      break;
+    case INVALID_FORMAT:
+        py::print("Aborting changes. A different docstring format was detected from what is specified.");
+      break;
+    }
 #endif
 }
 
@@ -111,10 +135,11 @@ std::map<std::string, int> check_docstrings(std::string &file_path) {
             };
 }
 
-void write_to_file_position(
+[[nodiscard]] WriteResult write_to_file_position(
     std::vector<FunctionInfo> &&infos,
     const std::string &file_path,
-    const DocstringFormatStyle &formatStyle
+    const DocstringFormatStyle &formatStyle,
+    const bool &allow_overwrite
 ) noexcept {
     std::fstream file;
 
@@ -139,6 +164,17 @@ void write_to_file_position(
             end_pos = val.docstring.end_line;
         }
 
+        if (val.docstring.detected_format_style.has_value()) {
+            if (!allow_overwrite && *val.docstring.detected_format_style != formatStyle) {
+                return INVALID_FORMAT;
+            }
+            if (allow_overwrite && *val.docstring.detected_format_style != formatStyle) {
+                const auto pos = val.docstring.remove_old_format_style();
+                if (pos >= 0)
+                    start_pos = pos;
+            }
+        }
+
         if (start_pos < 0 || end_pos - 1 < 0) {
             break;
         }
@@ -165,25 +201,25 @@ void write_to_file_position(
         lines.insert(lines.begin() + start_pos, docstring_format->docstring());
     }
 
-    {
-        std::ofstream out_file(file_path);
-        if (!out_file.is_open()) {
-            py::print("Error: Unable to open file for writing.");
-            std::cerr << "Error: Unable to open file for writing.\n";
-            return;
-        }
+    std::ofstream out_file(file_path);
+    if (!out_file.is_open()) {
+        py::print("Error: Unable to open file for writing.");
+        std::cerr << "Error: Unable to open file for writing.\n";
+        return FILE_NOT_FOUND;
+    }
 
-        std::string output;
-        output.reserve(lines.size() * 80); // rough estimate
-        for (const auto &line : lines) {
-            output += line;
-            if (line.empty() || line[line.size() - 1] != '\n') {
-                output += '\n';
-            }
+    std::string output;
+    output.reserve(lines.size() * 80); // rough estimate
+    for (const auto &line : lines) {
+        output += line;
+        if (line.empty() || line[line.size() - 1] != '\n') {
+            output += '\n';
         }
-        out_file.write(output.data(), static_cast<std::streamsize>(output.size()));
-        out_file.close();
     }
+    out_file.write(output.data(), static_cast<std::streamsize>(output.size()));
+    out_file.close();
+
+    return SUCCESS;
 }
 
 
@@ -195,6 +231,7 @@ PYBIND11_MODULE(docstring_generator_ext, m) {
         "A function that parses a file",
         py::arg("file_path"),
         py::arg("formatStyle"),
+        py::arg("allow_overwrite") = false,
         "The file_path where automatically docstrings should be added.",
         "In which style should the Docstring be written."
     );

{docstring_generator_ext-2.0.2 → docstring_generator_ext-2.0.3}/src/docstringFormat.hpp

@@ -5,11 +5,20 @@
 #include <string>
 #include "FunctionFormat.hpp"
 
-std::string read_file(const std::string &file_path);
+enum WriteResult {
+    SUCCESS,
+    FAILURE,
+    FILE_NOT_FOUND,
+    INVALID_FORMAT
+};
+
+[[nodiscard]] std::optional<std::string>  read_file(const std::string &file_path);
 
 void get_docstring_arg_descr(FunctionInfo &functionInfo) noexcept;
 
-void parse_file(std::string &file_path, DocstringFormatStyle &formatStyle);
+[[nodiscard]] std::vector<FunctionInfo> createFunctionInfos(const std::string &text, const DocstringFormatStyle &formatStyle);
+
+void parse_file(const std::string &file_path, const DocstringFormatStyle &formatStyle, const bool &allow_overwrite = false);
 
 /*
  * {

{docstring_generator_ext-2.0.2 → docstring_generator_ext-2.0.3}/src/parser.cpp

@@ -349,6 +349,26 @@ void get_docstring_arg_descr(FunctionInfo &functionInfo) noexcept {
     }
 }
 
+void get_docstring_return_descr(FunctionInfo &functionInfo) noexcept {
+    if (functionInfo.docstring.docstring.empty()) {
+        return;
+    }
+
+    if (functionInfo.returns.description.empty()) {
+        const auto iter = std::ranges::search(functionInfo.docstring.docstring, std::string_view(">>"));
+        if (iter.empty()) {
+            return;
+        }
+
+        const auto start = std::ranges::distance(functionInfo.docstring.docstring.begin(), iter.end());
+        const auto end = functionInfo.docstring.docstring.find('\n', start);
+        if (end != std::string::npos && start > 0) {
+            functionInfo.returns.description = functionInfo.docstring.docstring.substr(start, end - start);
+            functionInfo.docstring.docstring.erase(start - 2, functionInfo.returns.description.size() + 3); // 3 = '>>' + '\n'
+        }
+    }
+}
+
 void get_exception(
     const pybind11::object &function_body,
     py::module &ast_module,
@@ -448,6 +468,7 @@ FunctionInfo analyze_function(
     auto offset = py::cast<uint32_t>(py::getattr(obj, "col_offset"));
 
     FunctionDocstring doc_str = get_docstring(py::reinterpret_borrow<py::object>(obj), ast_module);
+    doc_str.detect_format_style();
 
     auto returns = py::getattr(obj, "returns");
 
@@ -481,7 +502,7 @@ FunctionInfo analyze_function(
     }
 
     get_docstring_arg_descr(functionInfo);
-
+    get_docstring_return_descr(functionInfo);
 
     return functionInfo;
 }

{docstring_generator_ext-2.0.2 → docstring_generator_ext-2.0.3}/src/parser.hpp

@@ -39,6 +39,7 @@ std::vector<FunctionParameter> generate_function_parameters(
 
 void get_docstring_arg_descr(FunctionInfo &functionInfo) noexcept;
 
+void get_docstring_return_descr(FunctionInfo &functionInfo) noexcept;
 
 void get_exception(
     const pybind11::object &function_body,