Updates the format of documentation to match neeto-commons-frontend s…

…tyle. (#38)

* Migrated the general docs from neeto-commons-frontend.

* Moved pure array helpers documentation from commons-frontend and updated the permalink to the cist repo.

* Moved the pure general functions from neeto-commons-frontend and updated the permalink in all the documentation files.

* Moved the pure object helper functions documentaions from neeto-commons-frontend and updated the permalink in all the documentation files.

* Moved the pure string helper functions documentaions from neeto-commons-frontend and updated the permalink in all the documentation files.

* Added documentation for nullSafe function.

* Added the documentation for isPresent helper.

* Added documentation of the matchesImpl function.

* Added the documentation of the hyphenate function.

* Added documentation for nullSafe function.gst

* Added documentation for nullSafe function.gst

* Updated the folder structure in api documentation guidelines

* Replaced the available functions table in the index Readme.md file.

* Added new line on top of the development instructions header.

* Removed the readme from the pure folder inside the docs folder.

* Fixed the case of the title in the index Readme file.

* Updates the path to the documentations of individual functions.

* Linked API documentation logistics documentation in the index Readme file.

* Update docs/general/building-and-releasing.md

Co-authored-by: Abhay V Ashokan <[email protected]>

* Updated the title of the functions list table.

---------

Co-authored-by: bot-bigbinary <[email protected]>
Co-authored-by: Abhay V Ashokan <[email protected]>

README.md

@@ -9,7 +9,7 @@ A collection of common utility functions used across all our
 ## Contents
   - [Installation](#installation)
   - [Usage](#usage)
-  - [List of Pure Functions](#list-of-pure-functions)
+  - [Available functions](#available-functions)
   - [Development](#development)
 
 ## Installation
@@ -35,8 +35,8 @@ import { slugify } from "@bigbinary/neeto-cist";
 ```
 
 Exports several general utility functions that are used throughout neeto
-products. The functions are designed in a similar fashion as ramda so that they
-can easily interoperate with each other.
+products. The functions are structured in a manner reminiscent of Ramda,
+enabling seamless interoperability among them.
 
 Pure functions were designed to be fail fast. If you call `findById(10, null)`,
 it will throw error saying that it can't iterate through `null`.
@@ -46,77 +46,109 @@ failsafe alternative function will be prefixed with `_`. Example:
 `_findById(10, null)` returns `null`, `_findById(10, undefined)` returns
 `undefined` and `_findById(10, [{ id: 10 }])` returns `{ id: 10 }`.
 
-## List of Pure Functions
+## Available functions
 
 <table>
 <thead>
 <tr>
 <th>
 
-Name
+Array operations
+
+</th>
+<th>
+
+Object operations
+
+</th>
+<th>
+
+String operations
+
+</th>
+<th>
+
+General utility functions
 
 </th>
 </tr>
 </thead>
 <tbody>
-<tr></tr>
-<tr></tr>
 <tr>
 <td style="vertical-align: top;">
 
-- [findById](./docs/pure/arrays.md#findbyid)
-- [findIndexById](./docs/pure/arrays.md#findindexbyid)
-- [removeById](./docs/pure/arrays.md#removebyid)
-- [replaceById](./docs/pure/arrays.md#replacebyid)
-- [modifyById](./docs/pure/arrays.md#modifybyid)
-- [existsById](./docs/pure/arrays.md#existsbyid)
-- [findBy](./docs/pure/arrays.md#findby)
-- [findIndexBy](./docs/pure/arrays.md#findindexby)
-- [removeBy](./docs/pure/arrays.md#removeby)
-- [replaceBy](./docs/pure/arrays.md#replaceby)
-- [modifyBy](./docs/pure/arrays.md#modifyby)
-- [existsBy](./docs/pure/arrays.md#existsby)
-- [findLastBy](./docs/pure/arrays.md#findlastby)
-- [findLastIndexBy](./docs/pure/arrays.md#findlastindexby)
-- [filterBy](./docs/pure/arrays.md#filterby)
-- [countBy](./docs/pure/arrays.md#countby)
-- [renameKeys](./docs/pure/arrays.md#renamekeys)
-- [copyKeys](./docs/pure/arrays.md#copykeys)
-- [copyKeysDeep](./docs/pure/arrays.md#copykeysdeep)
-- [transformObjectDeep](./docs/pure/objects.md#transformobjectdeep)
-- [preprocessForSerialization](./docs/pure/objects.md#preprocessforserialization)
-- [keysToCamelCase](./docs/pure/objects.md#keystocamelcase)
-- [keysToSnakeCase](./docs/pure/objects.md#keystosnakecase)
-- [deepFreezeObject](./docs/pure/objects.md#deepfreezeobject)
-- [matches](./docs/pure/objects.md#matches)
-- [filterNonNull](./docs/pure/objects.md#filternonnull)
-- [slugify](./docs/pure/strings.md#slugify)
-- [humanize](./docs/pure/strings.md#humanize)
-- [snakeToCamelCase](./docs/pure/strings.md#snaketocamelcase)
-- [camelToSnakeCase](./docs/pure/strings.md#cameltosnakecase)
-- [capitalize](./docs/pure/strings.md#capitalize)
-- [hyphenate](./docs/pure/strings.md#hyphenate)
-- [truncate](./docs/pure/strings.md#truncate)
-- [noop](./docs/pure/general.md#noop)
-- [toLabelAndValue](./docs/pure/general.md#tolabelandvalue)
-- [getRandomInt](./docs/pure/general.md#getrandomint)
-- [randomPick](./docs/pure/general.md#randompick)
-- [dynamicArray](./docs/pure/general.md#dynamicarray)
-- [isNotEmpty](./docs/pure/general.md#isnotempty)
-- [isNot (alias notEquals)](./docs/pure/general.md#isnot_alias_notequals)
-- [isNotEqualDeep (alias notEqualsDeep)](./docs/pure/general.md#isnotequaldeep_alias_notequalsdeep)
-- [isNotPresent](./docs/pure/general.md#isnotpresent)
-- [isPresent](./docs/pure/general.md#ispresent)
-- [modifyWithImmer](./docs/pure/general.md#modifywithimmer)
+- [findById](docs/pure/arrays/findById.md)
+- [findIndexById](docs/pure/arrays/findIndexById.md)
+- [removeById](docs/pure/arrays/removeById.md)
+- [replaceById](docs/pure/arrays/replaceById.md)
+- [modifyById](docs/pure/arrays/modifyById.md)
+- [existsById](docs/pure/arrays/existsById.md)
+
+---
+
+- [findBy](docs/pure/arrays/findBy.md)
+- [findIndexBy](docs/pure/arrays/findIndexBy.md)
+- [removeBy](docs/pure/arrays/removeBy.md)
+- [replaceBy](docs/pure/arrays/replaceBy.md)
+- [modifyBy](docs/pure/arrays/modifyBy.md)
+- [existsBy](docs/pure/arrays/existsBy.md)
+- [findLastBy](docs/pure/arrays/findLastBy.md)
+- [findLastIndexBy](docs/pure/arrays/findLastIndexBy.md)
+- [filterBy](docs/pure/arrays/filterBy.md)
+- [countBy](docs/pure/arrays/countBy.md)
+
+---
+
+- [renameKeys](docs/pure/arrays/renameKeys.md)
+- [copyKeys](docs/pure/arrays/copyKeys.md)
+- [copyKeysDeep](docs/pure/arrays/copyKeysDeep.md)
 
 </td>
-</tr>
+<td  style="vertical-align: top;">
+
+- [matchesImpl](docs/pure/objects/matchesImpl.md)
+- [transformObjectDeep](docs/pure/objects/transformObjectDeep.md)
+- [keysToCamelCase](docs/pure/objects/keysToCamelCase.md)
+- [keysToSnakeCase](docs/pure/objects/keysToSnakeCase.md)
+- [serializeKeysToSnakeCase](docs/pure/objects/serializeKeysToSnakeCase.md)
+- [preprocessForSerialization](docs/pure/objects/preprocessForSerialization.md)
+- [deepFreezeObject](docs/pure/objects/deepFreezeObject.md)
+- [matches](docs/pure/objects/matches.md)
+- [filterNonNull](docs/pure/objects/filterNonNull.md)
 
-<tr></tr>
+</td>
+<td  style="vertical-align: top;">
+
+- [slugify](docs/pure/strings/slugify.md)
+- [humanize](docs/pure/strings/humanize.md)
+- [snakeToCamelCase](docs/pure/strings/snakeToCamelCase.md)
+- [camelToSnakeCase](docs/pure/strings/camelToSnakeCase.md)
+- [capitalize](docs/pure/strings/capitalize.md)
+- [hyphenate](docs/pure/strings/hyphenate.md)
+- [truncate](docs/pure/strings/truncate.md)
+
+</td>
+<td  style="vertical-align: top;">
+
+- [nullSafe](docs/pure/general/nullSafe.md)
+- [noop](docs/pure/general/noop.md)
+- [toLabelAndValue](docs/pure/general/toLabelAndValue.md)
+- [getRandomInt](docs/pure/general/getRandomInt.md)
+- [randomPick](docs/pure/general/randomPick.md)
+- [dynamicArray](docs/pure/general/dynamicArray.md)
+- [isNotEmpty](docs/pure/general/isNotEmpty.md)
+- [isNot (notEquals)](docs/pure/general/isNot.md)
+- [isNotPresent](docs/pure/general/isNotPresent.md)
+- [isPresent](docs/pure/general/isPresent.md)
+- [isNotEqualDeep (alias notEqualsDeep)](docs/pure/general/isNotEqualDeep.md)
+- [modifyWithImmer](docs/pure/general/modifyWithImmer.md)
+</td>
+<tr>
 </tbody>
 </table>
 
 ## Development
 
 - [Development instructions](./docs/general/development-instructions.md)
+- [API documentation logistics](./docs/general/api-documentation-logistics.md)
 - [Building and releasing](./docs/general/building-and-releasing.md)

docs/general/api-documentation-logistics.md

@@ -0,0 +1,55 @@
+# API documentation logistics
+
+We offer a meticulously organized API documentation to support developers in
+enhancing their comprehension of the functionalities available within the
+`@bigbinary/neeto-cist` package. This documentation serves the dual
+purpose of generating [JSDocs](https://jsdoc.app/), underscoring the importance
+of upholding a uniform format.
+
+To ensure a consistent structure for the documentation, it's necessary to follow
+the guidelines outlined below when adding a new utility or editing an existing
+one within the package:
+
+1. When adding a new utility, create a file with the same name as that of
+   function in the respective directory inside the `pure` directory based on its use case.
+2. Follow the format below to compose the function documentation:
+
+```
+## <function-name> ([source code](<perma-link>))
+
+<description>
+
+### Arguments:
+
+<Arguments as points>
+
+### Return value:
+
+<Return values as points>
+
+### Usage
+
+<Usage goes here>
+```
+
+3. Link to the source code should be attached using a
+   [permalink](https://docs.github.com/en/repositories/working-with-files/using-files/getting-permanent-links-to-files)
+   from GitHub instead of generic links. Whenever the function is edited in the
+   future, make sure to update the permalink to reference the latest version of
+   the function.
+4. `Arguments` and `Return value` sections may be omitted depending on the
+   function signature.
+5. In the `Usage` section, include comprehensive examples that demonstrate how
+   the function should be utilized in various scenarios. If a function requires
+   additional context, consider explaining the problem it solves using
+   real-world scenarios.
+6. Maintain a clear and concise language. Avoid unnecessary embellishments and
+   keep your descriptions succinct.
+7. Ensure that sentences are well-formed with proper punctuation.
+8. It's worth noting that when the document is converted to JSDoc, all headers
+   and bullet points will be excluded, leaving only the descriptive portion of
+   the function documentation.
+9. It's crucial to present examples in the `Usage` section within a code block.
+   The content within the code block will be parsed, and its contents will be
+   added within the [example](https://jsdoc.app/tags-example.html) tags in
+   JSDoc.

docs/general/building-and-releasing.md

@@ -1,18 +1,18 @@
-# Building and releasing.
+# Building and releasing
 
-The `@bigbinary/neeto-cist` package gets published to NPM when we merge a PR
-with `patch`, `minor` or `major` label to the `main` branch. The `patch` label
-is used for bug fixes, `minor` label is used for new features and `major` label
-is used for breaking changes. You can checkout the `Create and publish releases`
-workflow in GitHub Actions to get a live update.
+The `@bigbinary/neeto-cist` package gets published to NPM when we
+merge a PR with `patch`, `minor` or `major` label to the `main` branch. The
+`patch` label is used for bug fixes, `minor` label is used for new features and
+`major` label is used for breaking changes. You can checkout the
+`Create and publish releases` workflow in GitHub Actions to get a live update.
 
 In case if you missed to add the label, you can manually publish the package.
 For that first you need to create a PR to update the version number in the
 `package.json` file and merge it to the `main` branch. After merging the PR, you
 need to create a
-[new github release](https://github.com/bigbinary/neeto-cist/releases/new) from
-main branch. Whenever a new release is created with a new version number, the
-github actions will automatically publish the built package to npm. You can
+[new github release](https://github.com/bigbinary/neeto-cist/releases/new)
+from main branch. Whenever a new release is created with a new version number,
+the github actions will automatically publish the built package to npm. You can
 checkout the `Publish to npm` workflow in GitHub Actions to get a live update.
 
 Please note that before publishing the package, you need to verify the

docs/general/development-instructions.md

@@ -6,10 +6,11 @@
 3. Have a host application ready.
 4. Run `yarn build --watch` to automatically transpile code as you save the
    file. You can omit the `--watch` flag if you want to run the build only once.
-5. In a different terminal, run `yalc publish` to publish the neeto-cist to the
-   local yalc store.
-6. Run `yalc add @bigbinary/neeto-cist` to install the neeto-cist to the host
-   application.
-7. After making necessary changes to `neeto-cist`, run `yalc push` to push the
-   changes to the host application (assuming that you are in watch mode and the
-   changes are bundled automatically).
+5. In a different terminal, run `yalc publish` to publish the
+   neeto-cist to the local yalc store.
+6. Run `yalc add @bigbinary/neeto-cist` to install the
+   neeto-cist to the host application.
+7. After making necessary changes to `neeto-cist`, run `yalc push`
+   to push the changes to the host application (assuming that you are in watch
+   mode and the changes are bundled automatically).
+8. Video explanation on how to use yalc: https://youtu.be/F4zZFnrNTq8