PatchWork GenerateDocstring

tests/cicd/generate_docstring/cpp_test_file.cpp

@@ -6,11 +6,30 @@
 
 
 template<typename T>
+/**
+ * Adds two values of the same type.
+ * 
+ * @param a The first value to add.
+ * @param b The second value to add.
+ * @return The sum of the two values.
+ */
 T a_plus_b(T a, T b) {
     return a + b;
 }
 
 
+/**
+ * Executes a given SQL query on the provided SQLite database and retrieves the results.
+ * 
+ * The function prepares and executes the SQL query using the provided database connection.
+ * It processes each row of the result, storing column data as strings in a vector of strings, and
+ * collects these rows into a vector of vector of strings which represents the entire result set.
+ * 
+ * @param db A pointer to the SQLite database connection.
+ * @param query The SQL query to be executed as a string.
+ * @return A vector of vector of strings, where each inner vector represents a row of the query result.
+ *         Returns an empty result if the query preparation failed or if no rows are returned.
+ */
 std::vector<std::vector<std::string>> sqlite(sqlite3* db, const std::string& query) {
     std::vector<std::vector<std::string>> results;
     sqlite3_stmt* stmt;
@@ -38,6 +57,22 @@ std::vector<std::vector<std::string>> sqlite(sqlite3* db, const std::string& que
 
 
 template<typename T, typename F>
+/**
+ * Compares two items using a key mapping function and returns an integer based 
+ * on their values. This function leverages a key mapping function to extract 
+ * comparable values from the provided items, enabling a generic comparison 
+ * mechanism.
+ * 
+ * @param key_map A function or callable object that extracts a comparable value 
+ *                from an item of type T. This function must take a single 
+ *                argument of type T and return a value that can be compared 
+ *                using the relational operators.
+ * @param item1 The first item to be compared.
+ * @param item2 The second item to be compared.
+ * @return An integer: returns -1 if the value of item1 is less than the value 
+ *         of item2; returns 1 if the value of item1 is greater than the value 
+ *         of item2; returns 0 if both values are equal.
+ */
 int compare(F key_map, const T& item1, const T& item2) {
     auto val1 = key_map(item1);
     auto val2 = key_map(item2);
@@ -48,6 +83,13 @@ int compare(F key_map, const T& item1, const T& item2) {
 }
 
 
+/**
+ * Generates a random string consisting of alphabetic characters.
+ * The string includes both uppercase and lowercase letters.
+ * 
+ * @param length The length of the random string to be generated.
+ * @return A random string of specified length containing alphabetic characters.
+ */
 std::string random_alphabets(int length) {
     static const std::string chars =
         "abcdefghijklmnopqrstuvwxyz"

tests/cicd/generate_docstring/java_test_file.java

@@ -1,8 +1,24 @@
 class Test {
+    /**
+     * Computes the sum of two integers.
+     * 
+     * @param a The first integer to be added.
+     * @param b The second integer to be added.
+     * @return The sum of the two input integers.
+     */
     public static int a_plus_b(Integer a, Integer b) {
         return a + b;
     }
 
+    /**
+     * Compares two objects based on their mapped comparable values.
+     * It uses a specified key mapping function to transform both objects into Comparable values and determines their order.
+     * 
+     * @param keymap Function that maps an object to a Comparable value for comparison.
+     * @param a The first object to be compared.
+     * @param b The second object to be compared.
+     * @return -1 if the mapped value of 'a' is less than 'b', 1 if it is greater, and 0 if they are equal.
+     */
     public static int a_plus_b(Function<Object, Comparable> keymap, object a, Object b) {
         if (keymap(a) < keymap(b)) {
             return -1;

tests/cicd/generate_docstring/js_test_file.py.js

@@ -1,8 +1,23 @@
 
+/**
+ * Computes the sum of two numbers.
+ * @param {number}  a - The first number to add.
+ * @param {number}  b - The second number to add.
+ * @returns {number} The sum of the two numbers.
+ */
 function a_plus_b(a, b) {
     return a + b;
 }
 
+/**
+ * Compares two objects based on the specified key and returns a numeric value
+ * that indicates their relative order.
+ * @param {string} keymap - The key used to compare the values in the objects.
+ * @param {Object} a - The first object to be compared.
+ * @param {Object} b - The second object to be compared.
+ * @returns {number} Returns -1 if the first object's key value is less than
+ * the second, 1 if greater, and 0 if they are equal.
+ */
 const compare = function (keymap, a, b) {
     if (a[keymap] < b[keymap]) {
         return -1;
@@ -13,6 +28,13 @@ const compare = function (keymap, a, b) {
     }
 }
 
+/**
+ * Executes a SQL query on a SQLite database and applies a callback function to each result row.
+ * @param {Object} db - The SQLite database object on which the query will be executed.
+ * @param {string} query - The SQL query string to be executed against the database.
+ * @param {function} callback - The callback function to be executed for each row of the result set.
+ * @returns {void} This function does not return a value.
+ */
 const sqlite = (db, query, callback) => {
     db.serialize(function () {
         db.each(query, callback);

tests/cicd/generate_docstring/kotlin_test_file.kt

@@ -5,9 +5,29 @@ import java.sql.ResultSet
 import kotlin.random.Random
 
 
+/**
+ * Computes the sum of two numbers, converting them to Double.
+ * 
+ * This function takes two parameters of a type that extends Number,
+ * converts them to Double, and returns their sum as a Double.
+ * 
+ * @param a The first number to add, must extend Number.
+ * @param b The second number to add, must extend Number.
+ * @return The sum of a and b as a Double.
+ */
 fun <T : Number> aPlusB(a: T, b: T): Double = a.toDouble() + b.toDouble()
 
 
+/**
+ * Executes a SQL query on the given database connection and returns the 
+ * results as a list of rows, where each row is a list of column values.
+ * 
+ * @param db The database connection to be used for executing the query.
+ * @param query The SQL query string to be executed on the database.
+ * @return A list of lists, where each inner list represents a row of the 
+ * query result. Each element of the inner list corresponds to a column value 
+ * in that row. If the query returns no results, an empty list is returned.
+ */
 fun sqlite(db: Connection, query: String): List<List<Any?>> {
     db.createStatement().use { statement ->
         statement.executeQuery(query).use { resultSet ->
@@ -27,6 +47,14 @@ fun sqlite(db: Connection, query: String): List<List<Any?>> {
 }
 
 
+/**
+ * Compares two items based on a specified key mapping function and returns an integer indicating their order.
+ * 
+ * @param keyMap A function that maps an item of type T to a comparable key of type R. This function is used to determine the attribute by which the comparison occurs.
+ * @param item1 The first item of type T to be compared.
+ * @param item2 The second item of type T to be compared.
+ * @return An integer: -1 if item1 is less than item2, 1 if item1 is greater than item2, and 0 if they are equal based on the key map.
+ */
 fun <T, R : Comparable<R>> compare(keyMap: (T) -> R, item1: T, item2: T): Int {
     return when {
         keyMap(item1) < keyMap(item2) -> -1
@@ -36,6 +64,13 @@ fun <T, R : Comparable<R>> compare(keyMap: (T) -> R, item1: T, item2: T): Int {
 }
 
 
+/**
+ * Generates a random string of alphabets with the specified length.
+ * The string includes both lowercase and uppercase letters.
+ * 
+ * @param length The number of characters in the generated string.
+ * @return A string composed of random alphabetical characters.
+ */
 fun randomAlphabets(length: Int): String {
     val charPool = ('a'..'z') + ('A'..'Z')
     return (1..length)

tests/cicd/generate_docstring/python_test_file.py

@@ -1,15 +1,44 @@
 # fmt: off
 def a_plus_b(a, b):
+    """Calculate the sum of two values.
+
+    Args:
+        a (int, float): The first value to be added.
+        b (int, float): The second value to be added.
+
+    Returns:
+        int, float: The sum of the input values a and b.
+    """
     return a + b
 
 
 def sqlite(db, query):
+    """Execute a SQL query on the given database connection and return all fetched results.
+
+    Args:
+        db (sqlite3.Connection): The database connection object.
+        query (str): The SQL query to be executed.
+
+    Returns:
+        list: A list of tuples representing the rows fetched from the database.
+    """
     cursor = db.cursor()
     cursor.execute(query)
     return cursor.fetchall()
 
 
 def compare(key_map, item1, item2):
+    """
+    Compares two items based on a key function and returns an integer indicating their order.
+
+    Args:
+        key_map (callable): A function that takes an item and returns a value to compare.
+        item1 (any): The first item to compare.
+        item2 (any): The second item to compare.
+
+    Returns:
+        int: Returns -1 if the value of item1 is less than the value of item2, 1 if the value of item1 is greater than the value of item2, or 0 if they are equal.
+    """
     if key_map(item1) < key_map(item2):
         return -1
     elif key_map(item1) > key_map(item2):
@@ -21,4 +50,12 @@ def compare(key_map, item1, item2):
 def random_alphabets(
         length: int
 ):
+    """Generate a random string of alphabets of specified length.
+
+    Args:
+        length (int): The length of the random string to generate.
+
+    Returns:
+        str: A string consisting of randomly selected alphabetic characters, both uppercase and lowercase.
+    """
     return ''.join(random.choices(string.ascii_letters, k=length))