@danielcobo/docs

docs

Automate repo documentation

🧭 Table of contents

• ✨ Benefits
• 🎒 Requierments
• 🚀 Quickstart
• 📘 Documentation
• 🆘 Troubleshooting
• 🤝 Contributing
• 🧪 Testing
• ⚖️ License

✨ Benefits

• [x] Boilerplates for LICENSE and README
• [x] Customisable
• [x] Simple handlebars template
• [x] Much less overhead than JSDoc
• [x] Leverages data from package.json

🎒 Requierments

To use this package you will need:

• NodeJS

🚀 Quickstart

Setup

In the terminal run:

npm install @danielcobo/docs -D

_{Note: Don't forget to init your package using npm init first.}

In your package.json file add "docs": "docs" to the list of scripts.

  "scripts": {
    "docs": "docs"
  },

_{Note: In case you're wondering, @danielcobo/ is just a namespace scope - an NPM feature. Scopes make it easier to name modules and improve security.}

Usage

Important: running the code below will overwrite existing README.md and LICENSE.md

In the terminal run:

npm run docs

If there are no template files (README.hbs and LICENSE.hbs) boilerplates will be generated to get you started.

Do not edit the .md files directly, instead edit the .hbs templates. After that run npm run docs to regenerate the documentation.

The data passed to templates consists of :

• definition - an array of definitions based on JSDoc style comments in your code
• repo - object consisting of data parsed from package.json

For details see documentation below.

There are also 5 HandlebarsJS helpers you can use:

• noscope
• nogit
• major
• minor
• typecode

Helper example	Description
{{noscope repo.name}}	returns repository name without the scope. Useful for links, etc.
{{nogit repo.repository.url}}	returns the git repository url
{{major repo.version}}	returns major semver version (example: 1)
{{minor repo.version}}	returns minor semver version (example: 1.0)
{{{typecode type}}}	returns type names split by | and with appropriate anchor links.

_{Note: replace type with appropriate scoped reference.}

You can refer to Handlebars docs regarding the templating syntax.

📘 Documentation

Definition : Object

Name	Type	Description
description	string	Type/function description text
name	string	Type/function name
type	string	Type (i.e. function, method, object...)
isTypedef	boolean	True if typedef (else assume function)
param	Array.Param	Function parameters
property	Array.Property	Type/function properties
returns	ReturnValue	Function return value
source	Source	Type/function definition source

_{Source: src/parseComments.js:164}

ReturnValue : Object

Name	Type	Description
type	string	Data type of return value
description	string	Description of return value

_{Source: src/parseComments.js:142}

Source : Object

Name	Type	Description
line	number	Source line number
path	string	Source file path
url	string	Relative source file url

_{Source: src/parseComments.js:134}

Property : Object

Type definition property

Name	Type	Description
name	string	Property name
type	string	Property value data type
description	string	Property description
optional	boolean	True/false if property is optional

_{Source: src/parseComments.js:113}

Param : Object

Function parameter

Name	Type	Description
name	string	Parameter name
type	string	Argument data type
description	string	Parameter description
optional	boolean	True/false if parameter is optional
default	*	Default argument value

_{Source: src/parseComments.js:94}

Data : Object

Name	Type	Description
definition	Array.Definition	Definition object
repo	Package	Object of package.json data

_{Source: src/index.js:19}

🆘 Troubleshooting

Remember to use run when calling the script.

❌ npm docs will fail.

✅ npm run docs will work.

🤝 Contributing

Anyone can contribute

Contributions come in many shapes and sizes. All are welcome. You can contribute by:

• asking questions
• suggesting features
• sharing this repo with friends
• improving documentation (even fixing typos counts 😉)
• providing tutorials (if you do, please let me know, I would love to read them)
• improving tests
• contributing code (new features, performance boosts, code readability improvements..)

Rules for contributions

General guidelines:

• there are no dumb questions
• be polite and respectful to others
• do good

When coding remember:

• working > maintainability > performance
• best code is no code
• be descriptive when naming
• keep it DRY
• do test

Contribution licence: All contributions are considered to be under same license as this repository.

🧪 Testing

Testing suite: 🃏 Jest | Test command: npm test

Mutation testing suite: 👽 Stryker Mutator | Mutation test command: npm run mutation

If you intend to develop further or contribute code, then please ensure to write and use testing. Strive for 100% code coverage and high mutation scores. Mutation score 100 is great, but it's not always neccessary (if there are valid reasons).

⚖️ License

MIT License