OpenFn / OpenFn/docs

`common` Update docstring

Open
#417 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
23
Forks
20
Avg merge
3d 1h
Merged PRs (30d)
6

Description

Description

Inspect the jsdocs for all functions in packages/common and make sure they align with what the function is suppose to do.
Add examples with captions for functions that returns {Operation}

Suggestions
Improvements suggestion for each() function

/**
 * Scopes an array of data based on a JSONPath, a function, or an object.
 * Useful when the source data has `n` items you would like to map to
 * an operation.
 * The operation will receive a slice of the data based on each item
 * of the JSONPath, function result, or the provided object.
 *
 * Note: It's the responsibility of the provided operation to ensure that
 * the results make their way back into the state's references.
 *
 * It should be designed to handle each item in the scoped data.
 * The Promise resolves after applying the operation on each item in the scoped data.
 * @public
 * @example <caption>Using JSONPath referencing a point in `state`</caption>
 * each("$.data.users[*]",
 *   create("SObject",
 *     field("FirstName", sourceValue("$.firstName"))
 *   )
 * )
 *
 * @example <caption>Using a function to be called with `state`</caption>
 * each(state=> state.data.users,
 *   create("SObject",
 *     field("FirstName", sourceValue("$.firstName"))
 *   )
 * )
 * @example <caption>Using an Object Literal of the data itself.</caption>
 * each(dataValue('users'),
 *   create("SObject",
 *     field("FirstName", sourceValue("$.firstName"))
 *   )
 * )
 *
 * @function
 *
 * @param {String|Function|Object} dataSource - JSONPath referencing a point in `state`, a function that takes state and returns an array of data, or an object representing data itself.
 *   - If a string, it represents a JSONPath pointing to a location in the `state` object.
 *   - If a function, it should take the `state` as an argument and return an array of data.
 *   - If an object, it returns an Object Literal of the data itself.
 *
 * @param {Function} operation -  The operation that takes `state` and returns a modified `state`.
 *
 * @returns {Operation}
 */
export function each(dataSource, operation) {// Implementation of the function goes here }

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by inspecting the JSDoc comments for all functions in packages/common, comparing each description with the function behavior. Add captions and examples for functions returning Operation, using the suggested each() documentation as a guide. Done means the common package docstrings accurately describe their functions and include the requested examples.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.