Example 1: Type Guard Functions Python
From marshmallow (Python) - Functions that check object types often lack clear parameter documentation.
Before
def is_generator(obj) -> typing.TypeGuard[typing.Generator]:
"""Return True if obj is a generator."""
return inspect.isgeneratorfunction(obj) or inspect.isgenerator(obj)
After
def is_generator(obj) -> typing.TypeGuard[typing.Generator]:
"""Return True if ``obj`` is a generator.
This checks both whether ``obj`` is a generator function using
``inspect.isgeneratorfunction()`` and whether ``obj`` is an
already-created generator object using ``inspect.isgenerator()``.
"""
return inspect.isgeneratorfunction(obj) or inspect.isgenerator(obj)
Improvement: Added detailed parameter documentation and expanded docstring with usage notes.
Example 2: Utility Functions Python
From marshmallow (Python) - Data extraction utilities often have minimal or no docstrings.
Before
def is_collection(obj) -> typing.TypeGuard[typing.Iterable]:
return is_iterable_but_not_string(obj) and not isinstance(obj, Mapping)
After
def is_collection(obj) -> typing.TypeGuard[typing.Iterable]:
"""Return True if ``obj`` is a collection type, e.g. list, tuple, queryset.
This function identifies collection types while excluding:
- Strings (which are iterable but not collections in this context)
- Mapping types (dict-like objects)
Useful for type narrowing in type-checked code.
"""
return is_iterable_but_not_string(obj) and not isinstance(obj, Mapping)
Improvement: Added complete docstring with parameter docs, behavior description, and use case context.
Example 3: Async Testing Helpers JavaScript
From nock (JavaScript) - Test utility functions often have minimal documentation for complex options.
Before
function Back(fixtureName, options, nockedFn) {
if (!Back.fixtures) {
throw new Error('Back requires nock.back.fixtures to be set')
}
// ... implementation
}
After
/**
* nock the current function with the fixture given
*
* @param {string} fixtureName - The name of the fixture, e.g. 'foo.json'
* @param {object} [options] - Optional extra options for nock with
* @param {function} [nockedFn] - Optional callback function to execute with the fixture loaded
* @returns {Promise} Resolves to {nockDone, context} when nockedFn is undefined
*/
function Back(fixtureName, options, nockedFn) {
if (!Back.fixtures) {
throw new Error('Back requires nock.back.fixtures to be set')
}
// ... implementation
}
Improvement: Added JSDoc comment with parameter types, descriptions, and return value documentation.