doc-code v0.0.1

documenting a program

• general workflow
• step by step
• all commands

general workflow

1. Write abstract program design.
2. Write a doc about the file structure in the program. Changes of this doc can be reflected in actual file structure.
3. Generate empty files from the doc above. Changes in file structure can be reflected in the file structure doc.
4. Write doc per code file.
5. Generate code files from the docs above.

step by step

1. Write an abstract design for your program in a .md file.

2. Add docmate configuration to package.json. You can modify this configuration and run dm genfile to reflect the change. This command can create new files and directories, modify first-line comment in files and modify directory doc, but can't delete files nor directories. You have to delete them manually.

   "docmate": {
       "ignore": [
           "node_modules",
           ".gitignore"
       ],
       "fileStruct": {
           "bin": {
               ".": "contain executable files",
               "foo.js": "main executable file as a router to other executable files in this directory"
           },
           "lib": {
               ".": "contains most of the source code",
               "bar.js": "provide functions for executables"
           },
           "test": {
               ".": "contains all test related files",
               "lib": {
                   ".": "contains test files for files under lib",
                   "bar.t.js": "test lib/bar.js"
               }
           }
       }
   }

3. Run dm genfile to generate the files and directories from docmate.fileStruct in package.json. File rename, delete, create and changes in the first-line comment in files can be reflected to docmate.fileStruct in package.json by running dm genstruct. You can ignore changes for files specified in docmate.ignore in package.json.

4. Write per-file doc in *.*.md files.

   This file is to ...
   
   To achieve that, we need a function like this:
   ```
   function foo () {}
   ```
   We also need a function like this:
   ```
   function bar () {}
   ```
   
   Below are the steps:
   1. Call foo so that ...
   ```
   foo();
   ```
   2. Call bar so that ...
   ```
   bar();
   ```

5. Run dm undoc[ files] to generate or update code files from *.*.md files.

6. Run dm doc[ files] to generate or update *.*.md files from code files.

all commands

• dm genfile generate or update files from docmate.fileStruct
• dm genstruct generate or update docmate.fileStruct from existing files
• dm gencode[ files] generate or update code files from *.*.md files
• dm gendoc[ files] generate or update *.*.md files from code files
• dm deldoc delete all *.*.md files that have corresponding code files
• dm delcode delete all code files that have corresponding *.*.md files
• dm cleandoc[ files] remove code blocks from *.*.md files