PatchWork GenerateDocstring

tests/cicd/generate_docstring/cpp_test_file.cpp

@@ -6,11 +6,27 @@
 
 
 template<typename T>
+/**
+ * Computes the sum of two elements.
+ * 
+ * @param a The first element to be added.
+ * @param b The second element to be added.
+ * @return The result of adding the two elements.
+ */
+
 T a_plus_b(T a, T b) {
     return a + b;
 }
 
 
+/**
+ * Executes a SQL query on the given SQLite database and retrieves the results as a vector of vector of strings.
+ * Each inner vector represents a row from the executed query, and each string within the inner vector represents a column value.
+ * 
+ * @param db Pointer to the SQLite database connection object.
+ * @param query The SQL query string to be executed on the SQLite database.
+ * @return A vector of vectors of strings containing the resulting rows and columns from the query. If the query fails to prepare, returns an empty vector.
+ */
 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 +54,16 @@ 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 to extract a value for comparison.
+ * 
+ * @param key_map A function or functor that maps an item of type T to a comparable value.
+ * @param item1 The first item to be compared.
+ * @param item2 The second item to be compared.
+ * @return An integer: -1 if the value associated with item1 is less than item2,
+ *         1 if the value associated with item1 is greater than item2,
+ *         or 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 +74,13 @@ int compare(F key_map, const T& item1, const T& item2) {
 }
 
 
+/**
+ * Generates a random string composed solely of alphabets (both uppercase and lowercase).
+ * 
+ * @param length The desired length of the random string to be generated.
+ * @return A random string of the specified length, containing only 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 {
+    /**
+     * Calculates 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 integers.
+     */
     public static int a_plus_b(Integer a, Integer b) {
         return a + b;
     }
 
+    /**
+     * Compares two objects using a provided key mapping function and returns an integer result based on their order.
+     * 
+     * @param keymap A function that maps an object to a Comparable value, which is used for the comparison.
+     * @param a The first object to be compared.
+     * @param b The second object to be compared.
+     * @return An integer indicating the order of the objects: -1 if the first object is less than the second,
+     *         1 if the first object is greater than the second, 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 @@
 
+/**
+ * Returns the sum of two numbers.
+ * @param {number} a - The first number to be added.
+ * @param {number} b - The second number to be added.
+ * @returns {number} The sum of the two input numbers.
+ */
 function a_plus_b(a, b) {
     return a + b;
 }
 
+/**
+ * Compares two objects based on a specified key and returns a numerical value indicating their order.
+ * @param {string}  keymap - A string representing the key to compare the objects by.
+ * @param {object}  a - The first object to compare.
+ * @param {object}  b - The second object to compare.
+ * @returns {number} A negative number if the first object is less than the second, 
+ *                   a positive number if the first object is greater than the second, 
+ *                   or 0 if they are equal based on the specified key.
+ */
 const compare = function (keymap, a, b) {
     if (a[keymap] < b[keymap]) {
         return -1;
@@ -13,6 +28,12 @@ const compare = function (keymap, a, b) {
     }
 }
 
+/**
+ * Executes a SQL query on a SQLite database, calling a callback function for each row returned by the query.
+ * @param {Object} db - An SQLite database object on which the query will be executed.
+ * @param {string} query - The SQL query string to be executed.
+ * @param {function} callback - A callback function to be invoked for each row in the result set. The function will receive the current row as its parameter.
+ */
 const sqlite = (db, query, callback) => {
     db.serialize(function () {
         db.each(query, callback);

tests/cicd/generate_docstring/kotlin_test_file.kt

@@ -5,9 +5,25 @@ import java.sql.ResultSet
 import kotlin.random.Random
 
 
+/**
+ * Sums two numbers that are subclasses of the Number class and returns the result as a Double.
+ * 
+ * @param a The first number of type T to be added.
+ * @param b The second number of type T to be added.
+ * @return The sum of the two numbers as a Double.
+ */
+
 fun <T : Number> aPlusB(a: T, b: T): Double = a.toDouble() + b.toDouble()
 
 
+/**
+ * Executes a given SQL query on the provided database connection and returns the results.
+ *
+ * @param db The database connection object to use for executing the query.
+ * @param query The SQL query to be executed.
+ * @return A list of lists, where each inner list represents a row of the result set, 
+ *         and each element in the row corresponds to a column value.
+ */
 fun sqlite(db: Connection, query: String): List<List<Any?>> {
     db.createStatement().use { statement ->
         statement.executeQuery(query).use { resultSet ->
@@ -27,6 +43,16 @@ fun sqlite(db: Connection, query: String): List<List<Any?>> {
 }
 
 
+/**
+ * Compares two items based on a key determined by the provided key mapping function.
+ * The key mapping function converts each item to a comparable result upon which the comparison is based.
+ * 
+ * @param keyMap A function that maps an item of type T to a Comparable key of type R.
+ * @param item1 The first item to be compared.
+ * @param item2 The second item to be compared.
+ * @return An integer representing the result of the comparison: -1 if item1 is less than item2,
+ *         1 if item1 is greater than item2, or 0 if they are equal according to the key mapping.
+ */
 fun <T, R : Comparable<R>> compare(keyMap: (T) -> R, item1: T, item2: T): Int {
     return when {
         keyMap(item1) < keyMap(item2) -> -1
@@ -36,6 +62,12 @@ fun <T, R : Comparable<R>> compare(keyMap: (T) -> R, item1: T, item2: T): Int {
 }
 
 
+/**
+ * Generates a random string consisting of uppercase and lowercase alphabets.
+ * 
+ * @param length The length of the desired random string.
+ * @return A random string of alphabets with the specified length.
+ */
 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,46 @@
 # fmt: off
 def a_plus_b(a, b):
+    """Adds two numbers together.
+
+    Args:
+        a (int or float): The first number to add.
+        b (int or float): The second number to add.
+
+    Returns:
+        int or float: The sum of the two numbers.
+    """
     return a + b
 
 
 def sqlite(db, query):
+    """Executes a SQL query on the given database and returns the results.
+
+    Args:
+        db (sqlite3.Connection): The database connection object on which the query should be executed.
+        query (str): The SQL query to be executed on the database.
+
+    Returns:
+        list: A list of tuples containing the rows returned by the query execution.
+    """
     cursor = db.cursor()
     cursor.execute(query)
     return cursor.fetchall()
 
 
 def compare(key_map, item1, item2):
+    """Compare two items using a key function.
+
+    Args:
+        key_map (Callable): A function that extracts a comparison key from each item.
+        item1 (Any): The first item to compare.
+        item2 (Any): The second item to compare.
+
+    Returns:
+        int: Returns -1 if the key from item1 is less than the key from item2,
+             1 if the key from item1 is greater than the key from item2,
+             and 0 if they are equal.
+    """
+
     if key_map(item1) < key_map(item2):
         return -1
     elif key_map(item1) > key_map(item2):
@@ -21,4 +52,12 @@ def compare(key_map, item1, item2):
 def random_alphabets(
         length: int
 ):
+    """Generates a random string of alphabets of a specified length.
+
+    Args:
+        length int: The length of the random string to be generated.
+
+    Returns:
+        str: A string containing random uppercase and lowercase alphabets of the specified length.
+    """
     return ''.join(random.choices(string.ascii_letters, k=length))