Simplify docs

docs/CLI.md

@@ -1,6 +1,6 @@
 # Command line interface
 
-Available with the same name of the package when installed globally:
+The CLI is a thin wrapper around the library Node API. It's available with the same name of the package when installed globally:
 
 ```bash
 swagger-jsdoc

docs/CONCEPTS.md

@@ -4,15 +4,15 @@ Please pay attention to the following shared information as it's based on recurr
 
 ## Definition and `apis`
 
-Before you start writing your specification and/or documentation, please keep in mind that there are two fundamental concepts you need to wrap you head around when working with `swagger-jsdoc` - definition object and input APIs.
+There are two fundamental concepts in `swagger-jsdoc` - definition object and input APIs.
 
-Definition object maps to [OpenAPI object](https://swagger.io/specification/#oasObject) and it is a required parameter.
+The definition object maps to [OpenAPI object](https://swagger.io/specification/#oasObject) and the input APIs are split source code parts which form the end specification.
 
-Input APIs are the code parts of your end specification. These could be files with JavaScript source code (or any other programming language) containing JSDoc comments. YAML files are also acceptable input and these are usually files containing definitions without logic: parameters, components, etc. The `apis` parameter is required.
+Parts of the specification can be placed in annotated JSDoc comments in non-compiled logical files. These specification parts stand close to their implementation.
 
-The list of `apis` can be passed either as arguments of the CLI or through the `apis` option.
+Other parts of the specification can be directly written in YAML files. These are usually parts containing static definitions which are referenced from jsDoc comments parameters, components, anchors, etc. which are not so relevant to the API implementation.
 
-To illustrate with an example, given `swaggerDefinition.js`:
+Given the following definition `swaggerDefinition.js`:
 
 ```javascript
 module.exports = {
@@ -24,29 +24,22 @@ module.exports = {
 };
 ```
 
-One way you can make use of this definition is by the CLI:
-
-```sh
-$ swagger-jsdoc -d swaggerDefinition.js src/route*.js
-```
-
-If you prefer to skip the `apis` files selection and still use the CLI, you will need to set `apis` array containing `src/route*.js` through the options.
+The end `swaggerSpecification` will be a result of following:
 
 ```javascript
-const swaggerJSDoc = require('swagger-jsdoc');
+const swaggerJsdoc = require('swagger-jsdoc');
+const swaggerDefinition = require('./swaggerDefinition');
 
 const options = {
-  swaggerDefinition: { ... }, // could be the same definition of above
+  swaggerDefinition,
   apis: ['./src/routes*.js'],
 };
 
-const swaggerSpec = swaggerJSDoc(options);
+const swaggerSpecification = swaggerJsdoc(options);
 ```
 
 ## File selection patterns
 
-Note that `swagger-jsdoc` uses [node glob](https://github.com/isaacs/node-glob) module in the background when taking your files. This means that you can use patterns such as `*.js` to select all javascript files or `**/*.js` to select all javascript files in sub-folders recursively.
-
-Paths provided are relative to the current directory from which you execute the program.
+`swagger-jsdoc` uses [node glob](https://github.com/isaacs/node-glob) for discovering your input files. You can use patterns such as `*.js` to select all javascript files or `**/*.js` to select all javascript files in sub-folders recursively.
 
-This concept is valid for both Node and CLI APIs.
+Paths are relative to the current working directory.

docs/GETTING-STARTED.md

@@ -3,7 +3,7 @@
 `swagger-jsdoc` returns the validated OpenAPI specification as JSON or YAML.
 
 ```javascript
-const swaggerJSDoc = require('swagger-jsdoc');
+const swaggerJsdoc = require('swagger-jsdoc');
 
 const options = {
   swaggerDefinition: {
@@ -16,17 +16,17 @@ const options = {
   apis: ['./src/routes*.js'],
 };
 
-const swaggerSpec = swaggerJSDoc(options);
+const swaggerSpecification = swaggerJsdoc(options);
 ```
 
 - `options.definition` is also acceptable. Pass an [oasObject](https://swagger.io/specification/#oasObject)
-- `options.apis` are resolved with [node-glob](https://github.com/isaacs/node-glob). Construct these patterns carefully in order to reduce the number of possible matches which will speed up discovery of files. Values are relative to the current working directory, not the application serving the APIs.
+- `options.apis` are resolved with [node-glob](https://github.com/isaacs/node-glob). Construct these patterns carefully in order to reduce the number of possible matches speeding up files' discovery. Values are relative to the current working directory.
 
-Use any of the [swagger tools](https://swagger.io/tools/) to get the benefits of your `swaggerSpec`.
+Use any of the [swagger tools](https://swagger.io/tools/) to get the benefits of your `swaggerSpecification`.
 
 ## Annotating source code
 
-Placing `@swagger` or `@openapi` on top of a YAML formatted piece of documentation will source the information in the specification:
+Place `@swagger` or `@openapi` on top of YAML-formatted specification parts:
 
 ```javascript
 /**

docs/README.md

@@ -1,9 +1,14 @@
 # Documentation
 
+Quick-start:
+
 - [Getting started](./GETTING-STARTED.md)
-- [Project goals](./GOALS.md)
-- [Fundamental concepts](./CONCEPTS.md)
 - [CLI](./CLI.md)
 - [Examples](../example)
+
+Before you submit an issue:
+
+- [Project goals](./GOALS.md)
+- [Fundamental concepts](./CONCEPTS.md)
 - [Tests](../test)
 - [Typescript](./TYPESCRIPT.md)

example/app/app.js

@@ -6,7 +6,7 @@ const express = require('express');
 const bodyParser = require('body-parser');
 const routes = require('./routes');
 const routes2 = require('./routes2');
-const swaggerJSDoc = require('../..');
+const swaggerJsdoc = require('../..');
 
 const PORT = process.env.PORT || 3000;
 
@@ -44,7 +44,7 @@ const options = {
 };
 
 // Initialize swagger-jsdoc -> returns validated swagger spec in json format
-const swaggerSpec = swaggerJSDoc(options);
+const swaggerSpec = swaggerJsdoc(options);
 
 // Serve swagger docs the way you like (Recommendation: swagger-tools)
 app.get('/api-docs.json', (req, res) => {