@duckdoc/cli

Code documentation as easy as running a single command. Never let your docs get out of sync with the code.

_{Built with love using nodejs • Brought to you by @inlife and other contributors}

Introduction

duckdoc is a simple and small service, designed with a single goal of simplifying the life of a developer.

At this point in time, the project is mainly targeted at teams working with javascript and nodejs environment, including JAMstack. Current version supports only javascript functions, no class support is yet implemented.

Features

• A single tool for the whole codebase
• Markdown-based editor
• Free for open-source projects
• Revision control and versioning support
• Automated change-set detection
• User-based documentaion "debt" caclulation

Installation

Currently, you can install duckdoc via npm:

npm i -g @duckdoc/cli

Later on we are planning on creating automated binary builds for every major platform with popular package manager support.

Usage

Running first time

When you run duckdoc first time, it will ask you to log in to your account. So make sure you are signed up on the website, before attempting to log in to account:

1. Click on auth.duckdoc.io/signup
2. Fill in account details
3. Create your team (or wait for an invitation to an existing one)

Now, you will be able to log in to your accoun on your local machine, to do that execute following command:

$ duckdoc login

And follow the instructions.

After you finished the login process, you now be able to run the duckdoc inside the project folder and "connect" it to an instance of the project on the duckdoc website. To do that:

1. Enter your project folder: cd ~/Projects/myproject
2. Run the tool: $ duckdoc
3. Follow instructions, and choose options as you see fit for your project

Done!

Running duckdoc

You should run duckdoc each time you've finished working on some piece of code, think of it as something like running git commit.

The command is:

$ duckdoc

Now each time you run it, the tool will fetch signatures of the entries (functions), and send them to our service, where workers will calculate and diff the changes, and report back with what needs to be done to "fix" inconsitencies.

How it works

As briefly mentioned above, duckdoc works by sending datasets containing signature definitions of the functions (currently only functions are supported), and file paths of where those signatures where extracted from. The data set looks something like that:

{
    "file": "src/utils/fs.js",
    "type": "js",
    "data": {
        "type": "function",
        "name": "createDirectory",
        "description": "This function allows to create a new directory, supports recursive paths",
        "params": [
            {
                "name": "path",
                "type": "String",
                "optional": false,
                "description": "A path where you wish to create directory at",
            },
            {
                "name": "isRecursive",
                "type": "Boolean",
                "optional": true,
                "description": "Whether it will try to create directory recursively",
            }
        ],
        "return": {
            "type": "Boolean",
            "description": "Whether or not function was able to create a directory"
        }
}

Each function is parsed and a similar signature to the one mentioned above is generated. That data then is sent to the duckdoc service, where it is compared with the previous definitions for the same project version (defined in package.json), and if any changes are detected there, user is given a "debt" (a set of issues) which he needs to resolve, otherwise it would continue to accumulate.

Every issue is has an author, a person responsible for creating it when the command is executed, and only that person is able to fix that issue.