Merge pull request #24 from g4s8/i23

chore: refactor ast parser and inspector

.github/workflows/go.yml

@@ -46,4 +46,4 @@ jobs:
       - name: golangci-lint
         uses: golangci/golangci-lint-action@v3
         with:
-          version: v1.53.3
+          version: v1.59.1

README.md

@@ -40,19 +40,26 @@ type Config struct {
 ## Usage
 
 ```go
-//go:generate envdoc -output <output_file_name> -type <target_type_name> 
+//go:generate envdoc -output <output_file_name>
 ```
 
- * `-output` (**required**) - Specify the output file name for the generated documentation.
- * `-type`: Specify the target struct type name to generate documentation for.
- If ommited, the next type after `go:generate` comment will be used.
- * `-format` (default: `markdown`) - Set output format type, either `markdown`,
- `plaintext`, `html`, or `dotenv`.
- * `-all` - Generate documentation for all types in the file.
- * `-env-prefix` - Environment variable prefix.
- * `-no-styles` - Disable built-int CSS styles for HTML format.
- * `-field-names` - Use field names instead of struct tags for variable names
-   if tags are not set.
+ * `-dir` (path string, *optional*) - Specify the directory to search for files. Default is the file dir with `go:generate` command.
+ * `-files` (glob string, *optional*) - File glob pattern to specify file names to process. Default is the single file with `go:generate`.
+ * `-types` (glob string, *optional*) - Type glob pattern for type names to process. If not specified, the next type after `go:generate` is used.
+ * `-output` (path string, **required**) - Output file name for generated documentation.
+ * `-format` (`enum(markdown, plaintext, html, dotenv)` string, *optional*) - Output format for documentation.  Default is `markdown`.
+ * `-no-styles` (`bool`, *optional*) - If true, CSS styles will not be included for `html` format.
+ * `-env-prefix` (`string`, *optional*) - Sets additional global prefix for all environment variables.
+ * `-field-names` (`bool`, *optional*) - Use field names as env names if `env:` tag is not specified.
+ * `-debug` (`bool`, *optional*) - Enable debug output.
+
+These params are deprecated and will be removed in the next major release:
+ * `-type` - Specify one type to process.
+ * `-all` - Process all types in a file.
+
+Both parameters could be replaced with `-types` param:
+ - Use `-types=Foo` instead of `-type=Foo`.
+ - Use `-types='*'` instead of `-all`.
 
 ## Example
 

_examples/all.md

@@ -0,0 +1,150 @@
+# Environment Variables
+
+## ComplexConfig
+
+ComplexConfig is an example configuration structure.
+It contains a few fields with different types of tags.
+It is trying to cover all the possible cases.
+
+ - `SECRET` (from-file) - Secret is a secret value that is read from a file.
+ - `PASSWORD` (from-file, default: `/tmp/password`) - Password is a password that is read from a file.
+ - `CERTIFICATE` (expand, from-file, default: `${CERTIFICATE_FILE}`) - Certificate is a certificate that is read from a file.
+ - `SECRET_KEY` (**required**) - Key is a secret key.
+ - `SECRET_VAL` (**required**, non-empty) - SecretVal is a secret value.
+ - `HOSTS` (separated by `:`, **required**) - Hosts is a list of hosts.
+ - `WORDS` (comma-separated, from-file, default: `one`) - Words is just a list of words.
+ - `COMMENT` (**required**, default: `This is a comment.`) - Just a comment.
+ - `ANON_USER` (**required**) - User is a user name.
+ - `ANON_PASS` (**required**) - Pass is a password.
+
+## NextConfig
+
+ - `MOUNT` (**required**) - Mount is a mount point.
+
+## FieldNames
+
+FieldNames uses field names as env names.
+
+ - `QUUX` - Quux is a field with a tag.
+ - Required is a required field.
+
+## Config
+
+ - `HOST` (separated by `;`, **required**) - Hosts name of hosts to listen on.
+ - `PORT` (**required**, non-empty) - Port to listen on.
+ - `DEBUG` (default: `false`) - Debug mode enabled.
+ - `PREFIX` - Prefix for something.
+
+## Config
+
+ - `START` (**required**, non-empty) - Start date.
+
+## Date
+
+Date is a time.Time wrapper that uses the time.DateOnly layout.
+
+
+## Settings
+
+Settings is the application settings.
+
+ - `DB_PORT` (**required**) - Port is the port to connect to
+ - `DB_HOST` (**required**, non-empty, default: `localhost`) - Host is the host to connect to
+ - `DB_USER` - User is the user to connect as
+ - `DB_PASSWORD` - Password is the password to use
+ - `DB_DISABLE_TLS` - DisableTLS is the flag to disable TLS
+ - `SERVER_PORT` (**required**) - Port is the port to listen on
+ - `SERVER_HOST` (**required**, non-empty, default: `localhost`) - Host is the host to listen on
+ - `SERVER_TIMEOUT_READ` (default: `30`) - Read is the read timeout
+ - `SERVER_TIMEOUT_WRITE` (default: `30`) - Write is the write timeout
+ - `DEBUG` - Debug is the debug flag
+
+## Database
+
+Database is the database settings.
+
+ - `PORT` (**required**) - Port is the port to connect to
+ - `HOST` (**required**, non-empty, default: `localhost`) - Host is the host to connect to
+ - `USER` - User is the user to connect as
+ - `PASSWORD` - Password is the password to use
+ - `DISABLE_TLS` - DisableTLS is the flag to disable TLS
+
+## ServerConfig
+
+ServerConfig is the server settings.
+
+ - `PORT` (**required**) - Port is the port to listen on
+ - `HOST` (**required**, non-empty, default: `localhost`) - Host is the host to listen on
+ - `TIMEOUT_READ` (default: `30`) - Read is the read timeout
+ - `TIMEOUT_WRITE` (default: `30`) - Write is the write timeout
+
+## TimeoutConfig
+
+TimeoutConfig is the timeout settings.
+
+ - `READ` (default: `30`) - Read is the read timeout
+ - `WRITE` (default: `30`) - Write is the write timeout
+
+## Config
+
+ - `APP_NAME` (default: `myapp`) - AppName is the name of the application.
+ - `SERVER_HOST` (**required**) - Host of the server.
+ - `SERVER_PORT` (**required**) - Port of the server.
+ - `SERVER_TIMEOUT_READ` (**required**) - ReadTimeout of the server.
+ - `SERVER_TIMEOUT_WRITE` (**required**) - WriteTimeout of the server.
+ - `DB_HOST` (**required**) - Host of the database.
+ - `DB_PORT` (**required**) - Port of the database.
+ - `DB_USER` (default: `user`) - User of the database.
+ - `DB_PASSWORD` - Password of the database.
+ - `LOG_LEVEL` (default: `info`) - Level of the logging.
+ - `LOG_FORMAT` (default: `json`) - Format of the logging.
+
+## Logging
+
+ - `LEVEL` (default: `info`) - Level of the logging.
+ - `FORMAT` (default: `json`) - Format of the logging.
+
+## Config
+
+Config holds the configuration for the database.
+
+ - `HOST` (**required**) - Host of the database.
+ - `PORT` (**required**) - Port of the database.
+ - `USER` (default: `user`) - User of the database.
+ - `PASSWORD` - Password of the database.
+
+## SslConfig
+
+SslConfig holds the configuration for the SSL of the database.
+
+ - `MODE` (default: `disable`) - SslMode of the database.
+ - `CERT` - SslCert of the database.
+ - `KEY` - SslKey of the database.
+
+## Config
+
+ - `HOST` (**required**) - Host of the server.
+ - `PORT` (**required**) - Port of the server.
+ - `TIMEOUT_READ` (**required**) - ReadTimeout of the server.
+ - `TIMEOUT_WRITE` (**required**) - WriteTimeout of the server.
+
+## TimeoutConfig
+
+TimeoutConfig holds the configuration for the timeouts of the server.
+
+ - `READ` (**required**) - ReadTimeout of the server.
+ - `WRITE` (**required**) - WriteTimeout of the server.
+
+## Config
+
+ - `START` - Start date.
+
+## Date
+
+Date is a time.Time wrapper that uses the time.DateOnly layout.
+
+
+## appconfig
+
+ - `PORT` (default: `8080`) - Port the application will listen on inside the container
+

_examples/all_files.go

@@ -0,0 +1,2 @@
+//go:generate go run ../ -output all.md -dir . -files * -types *
+package main

_examples/clean.sh

@@ -3,4 +3,4 @@
 set -euo pipefail
 cd ${0%/*}
 
-find . -type f \( -name "*.md" -or -name '*.txt' -or -name '*.html' \) ! -name "README.md" -exec rm -v {} \;
+find . -type f \( -name "*.md" -or -name '*.txt' -or -name '*.html' -or -name '*.env' \) ! -name "README.md" -exec rm -v {} \;

_examples/complex-fields.env

@@ -15,7 +15,6 @@
 ## FooBar is a field with a default value.
 ## (default: 'quuux')
 # FOO_BAR="quuux"
+#
 ## Required is a required field.
-## (required)
-# REQUIRED=""
 

_examples/complex-fields.html

@@ -76,17 +76,6 @@
       <article>
         <h1>Environment Variables</h1>
 
-  <h2>FieldNames</h2>
-<p>FieldNames uses field names as env names.</p>
-  <ul>
-    <li><code>FOO</code> - Foo is a single field.</li>
-    <li><code>BAR</code> - Bar and Baz are two fields.</li>
-    <li><code>BAZ</code> - Bar and Baz are two fields.</li>
-    <li><code>QUUX</code> - Quux is a field with a tag.</li>
-    <li><code>FOO_BAR</code> (default: <code>quuux</code>) - FooBar is a field with a default value.</li>
-    <li><code>REQUIRED</code> (<strong>required</strong>) - Required is a required field.</li>
-  </ul>
-
       </article>
     </section>
   </body>

_examples/complex-fields.md

@@ -9,5 +9,5 @@ FieldNames uses field names as env names.
  - `BAZ` - Bar and Baz are two fields.
  - `QUUX` - Quux is a field with a tag.
  - `FOO_BAR` (default: `quuux`) - FooBar is a field with a default value.
- - `REQUIRED` (**required**) - Required is a required field.
+ - Required is a required field.
 

_examples/complex-fields.txt

@@ -9,5 +9,5 @@ FieldNames uses field names as env names.
  * `BAZ` - Bar and Baz are two fields.
  * `QUUX` - Quux is a field with a tag.
  * `FOO_BAR` (default: `quuux`) - FooBar is a field with a default value.
- * `REQUIRED` (required) - Required is a required field.
+ * Required is a required field.
 

_examples/complex-nostyle.html

@@ -21,14 +21,10 @@ <h2>ComplexConfig</h2>
     <li><code>SECRET_KEY</code> (<strong>required</strong>) - Key is a secret key.</li>
     <li><code>SECRET_VAL</code> (<strong>required</strong>, non-empty) - SecretVal is a secret value.</li>
     <li><code>HOSTS</code> (separated by "<code>:</code>", <strong>required</strong>) - Hosts is a list of hosts.</li>
-    <li><code>WORDS</code> (comma-separated, from-file, default: <code>one,two,three</code>) - Words is just a list of words.</li>
+    <li><code>WORDS</code> (comma-separated, from-file, default: <code>one</code>) - Words is just a list of words.</li>
     <li><code>COMMENT</code> (<strong>required</strong>, default: <code>This is a comment.</code>) - Just a comment.</li>
-    <li>Anon is an anonymous structure.
-    <ul>
     <li><code>ANON_USER</code> (<strong>required</strong>) - User is a user name.</li>
     <li><code>ANON_PASS</code> (<strong>required</strong>) - Pass is a password.</li>
-    </ul>
-  </li>
   </ul>
 
   <h2>NextConfig</h2>
@@ -41,6 +37,7 @@ <h2>FieldNames</h2>
 <p>FieldNames uses field names as env names.</p>
   <ul>
     <li><code>QUUX</code> - Quux is a field with a tag.</li>
+    <li>Required is a required field.</li>
   </ul>
 
       </article>

_examples/complex.env

@@ -25,14 +25,11 @@
 ## (separated by ':', required)
 # HOSTS=""
 ## Words is just a list of words.
-## (comma-separated, from-file, default: 'one,two,three')
-# WORDS="one,two,three"
+## (comma-separated, from-file, default: 'one')
+# WORDS="one"
 ## Just a comment.
 ## (required, default: 'This is a comment.')
 # COMMENT="This is a comment."
-#
-## Anon is an anonymous structure.
-#
 ## User is a user name.
 ## (required)
 # ANON_USER=""
@@ -51,4 +48,6 @@
 #
 ## Quux is a field with a tag.
 # QUUX=""
+#
+## Required is a required field.
 

_examples/complex.html

@@ -87,14 +87,10 @@ <h2>ComplexConfig</h2>
     <li><code>SECRET_KEY</code> (<strong>required</strong>) - Key is a secret key.</li>
     <li><code>SECRET_VAL</code> (<strong>required</strong>, non-empty) - SecretVal is a secret value.</li>
     <li><code>HOSTS</code> (separated by "<code>:</code>", <strong>required</strong>) - Hosts is a list of hosts.</li>
-    <li><code>WORDS</code> (comma-separated, from-file, default: <code>one,two,three</code>) - Words is just a list of words.</li>
+    <li><code>WORDS</code> (comma-separated, from-file, default: <code>one</code>) - Words is just a list of words.</li>
     <li><code>COMMENT</code> (<strong>required</strong>, default: <code>This is a comment.</code>) - Just a comment.</li>
-    <li>Anon is an anonymous structure.
-    <ul>
     <li><code>ANON_USER</code> (<strong>required</strong>) - User is a user name.</li>
     <li><code>ANON_PASS</code> (<strong>required</strong>) - Pass is a password.</li>
-    </ul>
-  </li>
   </ul>
 
   <h2>NextConfig</h2>
@@ -107,6 +103,7 @@ <h2>FieldNames</h2>
 <p>FieldNames uses field names as env names.</p>
   <ul>
     <li><code>QUUX</code> - Quux is a field with a tag.</li>
+    <li>Required is a required field.</li>
   </ul>
 
       </article>

_examples/complex.md

@@ -12,11 +12,10 @@ It is trying to cover all the possible cases.
  - `SECRET_KEY` (**required**) - Key is a secret key.
  - `SECRET_VAL` (**required**, non-empty) - SecretVal is a secret value.
  - `HOSTS` (separated by `:`, **required**) - Hosts is a list of hosts.
- - `WORDS` (comma-separated, from-file, default: `one,two,three`) - Words is just a list of words.
+ - `WORDS` (comma-separated, from-file, default: `one`) - Words is just a list of words.
  - `COMMENT` (**required**, default: `This is a comment.`) - Just a comment.
- - Anon is an anonymous structure.
-   - `ANON_USER` (**required**) - User is a user name.
-   - `ANON_PASS` (**required**) - Pass is a password.
+ - `ANON_USER` (**required**) - User is a user name.
+ - `ANON_PASS` (**required**) - Pass is a password.
 
 ## NextConfig
 
@@ -27,4 +26,5 @@ It is trying to cover all the possible cases.
 FieldNames uses field names as env names.
 
  - `QUUX` - Quux is a field with a tag.
+ - Required is a required field.
 

_examples/complex.txt

@@ -12,11 +12,10 @@ It is trying to cover all the possible cases.
  * `SECRET_KEY` (required) - Key is a secret key.
  * `SECRET_VAL` (required, non-empty) - SecretVal is a secret value.
  * `HOSTS` (separated by `:`, required) - Hosts is a list of hosts.
- * `WORDS` (comma-separated, from-file, default: `one,two,three`) - Words is just a list of words.
+ * `WORDS` (comma-separated, from-file, default: `one`) - Words is just a list of words.
  * `COMMENT` (required, default: `This is a comment.`) - Just a comment.
- * Anon is an anonymous structure.
-   * `ANON_USER` (required) - User is a user name.
-   * `ANON_PASS` (required) - Pass is a password.
+ * `ANON_USER` (required) - User is a user name.
+ * `ANON_PASS` (required) - Pass is a password.
 
 ## NextConfig
 
@@ -27,4 +26,5 @@ It is trying to cover all the possible cases.
 FieldNames uses field names as env names.
 
  * `QUUX` - Quux is a field with a tag.
+ * Required is a required field.
 

_examples/config.env

@@ -1,20 +1,3 @@
 # Environment Variables
 
 
-## Config
-## Config is an example configuration structure.
-## It is used to generate documentation for the configuration
-## using the commands below.
-#
-## Hosts name of hosts to listen on.
-## (separated by ';', required)
-# HOST=""
-## Port to listen on.
-## (required, non-empty)
-# PORT=""
-## Debug mode enabled.
-## (default: 'false')
-# DEBUG="false"
-## Prefix for something.
-# PREFIX=""
-

_examples/config.html

@@ -76,17 +76,6 @@
       <article>
         <h1>Environment Variables</h1>
 
-  <h2>Config</h2>
-<p>Config is an example configuration structure.
-It is used to generate documentation for the configuration
-using the commands below.</p>
-  <ul>
-    <li><code>HOST</code> (separated by "<code>;</code>", <strong>required</strong>) - Hosts name of hosts to listen on.</li>
-    <li><code>PORT</code> (<strong>required</strong>, non-empty) - Port to listen on.</li>
-    <li><code>DEBUG</code> (default: <code>false</code>) - Debug mode enabled.</li>
-    <li><code>PREFIX</code> - Prefix for something.</li>
-  </ul>
-
       </article>
     </section>
   </body>