Skip to content

Commit

Permalink
Merge pull request #24 from g4s8/i23
Browse files Browse the repository at this point in the history
chore: refactor ast parser and inspector
  • Loading branch information
g4s8 authored Jul 30, 2024
2 parents f8f8c47 + 591db74 commit 14b5c52
Show file tree
Hide file tree
Showing 91 changed files with 4,075 additions and 2,207 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/go.yml
Original file line number Diff line number Diff line change
Expand Up @@ -46,4 +46,4 @@ jobs:
- name: golangci-lint
uses: golangci/golangci-lint-action@v3
with:
version: v1.53.3
version: v1.59.1
29 changes: 18 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
150 changes: 150 additions & 0 deletions _examples/all.md
Original file line number Diff line number Diff line change
@@ -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

2 changes: 2 additions & 0 deletions _examples/all_files.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
//go:generate go run ../ -output all.md -dir . -files * -types *
package main
2 changes: 1 addition & 1 deletion _examples/clean.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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 {} \;
3 changes: 1 addition & 2 deletions _examples/complex-fields.env
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,6 @@
## FooBar is a field with a default value.
## (default: 'quuux')
# FOO_BAR="quuux"
#
## Required is a required field.
## (required)
# REQUIRED=""

11 changes: 0 additions & 11 deletions _examples/complex-fields.html
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
2 changes: 1 addition & 1 deletion _examples/complex-fields.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

2 changes: 1 addition & 1 deletion _examples/complex-fields.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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.

7 changes: 2 additions & 5 deletions _examples/complex-nostyle.html
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand All @@ -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>
Expand Down
9 changes: 4 additions & 5 deletions _examples/complex.env
Original file line number Diff line number Diff line change
Expand Up @@ -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=""
Expand All @@ -51,4 +48,6 @@
#
## Quux is a field with a tag.
# QUUX=""
#
## Required is a required field.

7 changes: 2 additions & 5 deletions _examples/complex.html
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand All @@ -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>
Expand Down
8 changes: 4 additions & 4 deletions _examples/complex.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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.

8 changes: 4 additions & 4 deletions _examples/complex.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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.

17 changes: 0 additions & 17 deletions _examples/config.env
Original file line number Diff line number Diff line change
@@ -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=""

11 changes: 0 additions & 11 deletions _examples/config.html
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
Loading

0 comments on commit 14b5c52

Please sign in to comment.