docs: add documents

.github/workflows/coverage-tests.yaml

@@ -2,7 +2,6 @@ name: 100% Coverage
 
 on:
   workflow_dispatch:
-  pull_request:
 
 jobs:
   coverage:

CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# コントリビュート（参加）について
+
+## PullRequest 先
+
+- `main` ブランチ
+- PR に慣れていない方 👉 [How To Pull Request](https://github.com/Qithub-BOT/QiiCipher/blob/master/.github/HOW_TO_PULL_REQUEST.md) | QiiCipher | Qithub @ GitHub
+
+## マージ・ルール
+
+- `squash` `merge` マージ
+
+テストおよびレビューをパスした PR は、コミットを 1 つにまとめてマージします。そのため、**コミット・ログの綺麗さは気にする必要はありません**。どんどん試行錯誤してください。
+
+## PR 時の注意（レギュレーション）
+
+PR もしくは [Draft PR](https://github.blog/jp/2019-02-19-introducing-draft-pull-requests/) されると CI による各種テストが自動実行されます。
+
+これらのテストをパスしないと、レビューおよびマージは行われません。
+
+1. 構文・文法チェック（lint）と静的解析
+    - Golang 及びシェルスクリプトの構文テストが行われます。
+        - `shfmt` ........... シェル・スクリプトの構文チェック
+        - `shellcheck` ...... シェル・スクリプトの静的解析
+        - `gofmt` ........... Golang の構文チェック
+        - `golangci-lint` ... Golang の静的解析チェック
+2. ユニット・テスト
+    - `go test ./src/...` によるユニット・テストが行われます。`./.github/run-tests-coverage.sh` でもテストできます。
+3. カバレッジ・テスト
+    - 各々のパッケージ（ディレクトリ）にテストが 1 つでも設置されていた場合、カバレッジが 100% にならないとパスしません。
+    - 未カバーの箇所を確認したい場合は ``./.github/run-tests-coverage.sh --verbose` で確認できます。
+4. ドキュメントの更新チェック
+    - 各パッケージ（ディレクトリ）にある README.md は [gomarkdoc](https://github.com/princjef/gomarkdoc) で自動作成されたドキュメントです。
+    - CI では変更がドキュメントに反映されているかのテストが行われます。`./.github/update-docs.sh` で更新してください。(要 gomarkdoc)
+
+これらの確認や開発に必要な環境の Dockerfile を [./.devcontainer](.devcontainer) に用意しています。ご活用ください。
+
+## なんかわけわかめ
+
+- 遠慮なく [Discussions](https://github.com/Qithub-BOT/QiiTrans/discussions) の Q&A で聞いてください。

src/cache/README.md

@@ -0,0 +1,170 @@
+<!-- Code generated by gomarkdoc. DO NOT EDIT -->
+
+# cache
+
+```go
+import "github.com/Qithub-BOT/QiiTrans/src/cache"
+```
+
+Package cache は key\-value 型の簡易 DB です\.
+
+New\(\) でインスタンスが作成されると、テンポラリ・ディレクトリにキャッシュ用のディレクトリを作成します。 主に "Set\(\<翻訳前テキスト\>\, \<翻訳後テキスト\>\)" のように、翻訳結果をキャッシュするのに使われます。 デフォルトで共通のキャッシュ・ディレクトリを利用します。異なるキャッシュにしたい場合は任意のキャッシュ ID を指定します。
+
+```
+myCache := cache.New("myCache")
+```
+
+主なメソッド
+
+```
+Set(key, value) ... キャッシュの作成・更新をします
+Get(key) ... キャッシュから値を取得します。
+ClearAll() ... キャッシュ・ディレクトリを削除します。
+```
+
+## Index
+
+- [Constants](<#constants>)
+- [type TCache](<#type-tcache>)
+  - [func New(cacheID ...string) *TCache](<#func-new>)
+  - [func (c *TCache) ClearAll()](<#func-tcache-clearall>)
+  - [func (c *TCache) CloseDB()](<#func-tcache-closedb>)
+  - [func (c *TCache) Get(key string) (string, error)](<#func-tcache-get>)
+  - [func (c *TCache) GetPathDirCache() string](<#func-tcache-getpathdircache>)
+  - [func (c *TCache) GetValueInByte(keyHashed []byte) ([]byte, error)](<#func-tcache-getvalueinbyte>)
+  - [func (c *TCache) OpenDB() (err error)](<#func-tcache-opendb>)
+  - [func (c *TCache) Set(key string, value string) (err error)](<#func-tcache-set>)
+  - [func (c *TCache) hash64(content string) []byte](<#func-tcache-hash64>)
+
+
+## Constants
+
+```go
+const (
+    NameDirCacheDefault = "QiiTrans"
+)
+```
+
+## type [TCache](<https://github.com/Qithub-BOT/QiiTrans/blob/main/src/cache/TCache.go#L9-L13>)
+
+```go
+type TCache struct {
+    cacheDB      *badger.DB
+    NameDirCache string
+    PathDirTemp  string
+}
+```
+
+### func [New](<https://github.com/Qithub-BOT/QiiTrans/blob/main/src/cache/New.go#L10>)
+
+```go
+func New(cacheID ...string) *TCache
+```
+
+New は TCache の新規オブジェクトのポインタを返します\. デフォルトで共通のキャッシュを利用します。各々異なるキャッシュにしたい場合は、引数に ID を指定します\.
+
+<details><summary>Example</summary>
+<p>
+
+```go
+package main
+
+import (
+	"fmt"
+	"github.com/Qithub-BOT/QiiTrans/src/cache"
+)
+
+func main() {
+	// 汎用のキャッシュにしたくない場合は ID を指定する。この場合は "my sample DB".
+	c := cache.New("my sample DB")
+
+	// 終了時にキャッシュを削除したい場合は defer で ClearAll する
+	defer c.ClearAll()
+
+	phraseOriginal := "Hello, world!"
+	phraseTranslated := "世界よ、こんにちは！"
+
+	// Set でキャッシュに登録
+	_ = c.Set(phraseOriginal, phraseTranslated)
+
+	// Get でキャッシュから取得
+	result, _ := c.Get(phraseOriginal)
+
+	fmt.Println(result)
+}
+```
+
+#### Output
+
+```
+世界よ、こんにちは！
+```
+
+</p>
+</details>
+
+### func \(\*TCache\) [ClearAll](<https://github.com/Qithub-BOT/QiiTrans/blob/main/src/cache/TCache.ClearAll.go#L10>)
+
+```go
+func (c *TCache) ClearAll()
+```
+
+ClearAll はキャッシュ・データを削除します\.
+
+### func \(\*TCache\) [CloseDB](<https://github.com/Qithub-BOT/QiiTrans/blob/main/src/cache/TCache.CloseDB.go#L7>)
+
+```go
+func (c *TCache) CloseDB()
+```
+
+### func \(\*TCache\) [Get](<https://github.com/Qithub-BOT/QiiTrans/blob/main/src/cache/TCache.Get.go#L5>)
+
+```go
+func (c *TCache) Get(key string) (string, error)
+```
+
+Get はキャッシュから key を探索し、その値を文字列で返します\. キャッシュに key がない場合はエラーを返します\.
+
+### func \(\*TCache\) [GetPathDirCache](<https://github.com/Qithub-BOT/QiiTrans/blob/main/src/cache/TCache.GetPathDirCache.go#L6>)
+
+```go
+func (c *TCache) GetPathDirCache() string
+```
+
+GetPathDirCache は現在のキャッシュ先のディレクトリを返します\.
+
+### func \(\*TCache\) [GetValueInByte](<https://github.com/Qithub-BOT/QiiTrans/blob/main/src/cache/TCache.GetValueInByte.go#L6>)
+
+```go
+func (c *TCache) GetValueInByte(keyHashed []byte) ([]byte, error)
+```
+
+GetValueInByte はバイトデータにハッシュ化された keyHashed キーを使ってキャッシュを探索しバイトデータで返します\.
+
+### func \(\*TCache\) [OpenDB](<https://github.com/Qithub-BOT/QiiTrans/blob/main/src/cache/TCache.OpenDB.go#L8>)
+
+```go
+func (c *TCache) OpenDB() (err error)
+```
+
+### func \(\*TCache\) [Set](<https://github.com/Qithub-BOT/QiiTrans/blob/main/src/cache/TCache.Set.go#L11>)
+
+```go
+func (c *TCache) Set(key string, value string) (err error)
+```
+
+Set は value の値を key に割り当ててキャッシュします\.
+
+引数 key は、内部で 64 バイトの固定長にハッシュ化されるため、長さに依存しません\. この関数は、主に翻訳前の文と、翻訳後の文のキャッシュに使われます\. 呼び出しごとにキャッシュ DB を open/close するため、大量の連続呼び出しには向きません\. 大量に登録する場合は SetList\(\) 関数を利用してください\.
+
+### func \(\*TCache\) [hash64](<https://github.com/Qithub-BOT/QiiTrans/blob/main/src/cache/TCache.hash64.go#L6>)
+
+```go
+func (c *TCache) hash64(content string) []byte
+```
+
+hash64 は content の内容を 64 バイトのハッシュ値に変換します\.
+
+------
+
+Generated by [gomarkdoc](<https://github.com/princjef/gomarkdoc>)

src/cache/docs.go

@@ -6,7 +6,7 @@ New() でインスタンスが作成されると、テンポラリ・ディレ
 
   myCache := cache.New("myCache")
 
-メソッド
+主なメソッド
 
   Set(key, value) ... キャッシュの作成・更新をします
   Get(key) ... キャッシュから値を取得します。

src/engines/deepleng/README.md

@@ -0,0 +1,73 @@
+<!-- Code generated by gomarkdoc. DO NOT EDIT -->
+
+# deepleng
+
+```go
+import "github.com/Qithub-BOT/QiiTrans/src/engines/deepleng"
+```
+
+Package deepleng は DeepL の翻訳 API を使った翻訳エンジンです\.
+
+このエンジンを利用するには、DeepL PRO の無料／有料アカウントから発行したアクセス・トークン（認証キー/API キー）が必要です。
+
+\- アカウント登録後のアクセス・トークン確認先: https://www.deepl.com/pro-account/plan （認証キー）
+
+## Index
+
+- [Constants](<#constants>)
+- [func GetInfoAPI(p *engine.Properties) (engine.AccountInfo, error)](<#func-getinfoapi>)
+- [func GetURLBaseAPI(p *engine.Properties) string](<#func-geturlbaseapi>)
+- [func IsAPIKeyFree(apikey string) bool](<#func-isapikeyfree>)
+- [func New(cacheID ...string) *engine.Properties](<#func-new>)
+- [func Translate(p *engine.Properties, inText string, langFrom string, langTo string) (result string, err error)](<#func-translate>)
+
+
+## Constants
+
+```go
+const NameVarEnvAPIKey = "DEEPL_API_KEY"
+```
+
+## func [GetInfoAPI](<https://github.com/Qithub-BOT/QiiTrans/blob/main/src/engines/deepleng/GetInfoAPI.go#L13>)
+
+```go
+func GetInfoAPI(p *engine.Properties) (engine.AccountInfo, error)
+```
+
+GetInfoAPI はアクセス・トークンのアカウント情報のうち、engine\.AccountInfo に必要なものだけセットして返します\.
+
+## func [GetURLBaseAPI](<https://github.com/Qithub-BOT/QiiTrans/blob/main/src/engines/deepleng/GetURLBaseAPI.go#L5>)
+
+```go
+func GetURLBaseAPI(p *engine.Properties) string
+```
+
+## func [IsAPIKeyFree](<https://github.com/Qithub-BOT/QiiTrans/blob/main/src/engines/deepleng/IsAPIKeyFree.go#L6>)
+
+```go
+func IsAPIKeyFree(apikey string) bool
+```
+
+IsAPIKeyFree は apikey が無料枠のアクセストークンか返します\.
+
+## func [New](<https://github.com/Qithub-BOT/QiiTrans/blob/main/src/engines/deepleng/New.go#L8>)
+
+```go
+func New(cacheID ...string) *engine.Properties
+```
+
+New は翻訳エンジン（DeepL）の新規インスタンスのポインタを返します\.
+
+## func [Translate](<https://github.com/Qithub-BOT/QiiTrans/blob/main/src/engines/deepleng/Translate.go#L15>)
+
+```go
+func Translate(p *engine.Properties, inText string, langFrom string, langTo string) (result string, err error)
+```
+
+Translate は inText を langFrom から langTo に DeepL の翻訳 API を使って翻訳した結果を返します\.
+
+この関数は結果をキャッシュしません。別途、呼び出し元でキャッシュを行ってください\.
+
+------
+
+Generated by [gomarkdoc](<https://github.com/princjef/gomarkdoc>)

src/engines/deepleng/docs.go

@@ -2,6 +2,6 @@
 
 このエンジンを利用するには、DeepL PRO の無料／有料アカウントから発行したアクセス・トークン（認証キー/API キー）が必要です。
 
-登録後のアクセス・トークン確認先: https://www.deepl.com/pro-account/plan
+- アカウント登録後のアクセス・トークン確認先: https://www.deepl.com/pro-account/plan （認証キー）
 */
 package deepleng

src/engines/engine/Properties.GetAPIKey.go

@@ -2,6 +2,8 @@ package engine
 
 import "os"
 
+// GetAPIKey はコマンドのオプションで指定されたアクセス・トークンを返します.
+// オプションで指定がされていない場合は、環境変数から読み取って返します.
 func (p *Properties) GetAPIKey() string {
 	if p.apiKey != "" {
 		return p.apiKey

src/engines/engine/Properties.GetQuotaLeft.go

@@ -1,6 +1,6 @@
 package engine
 
-// GetQuotaLeft は API のリクエスト残量（翻訳可能文字数）を返します。有料アカウントや制限がない場合は -1 を返します.
+// GetQuotaLeft は API のリクエスト残量（翻訳可能文字数）を返します。有料アカウントなど、制限がない場合は -1 を返します.
 func (p *Properties) GetQuotaLeft() (int, error) {
 	info, err := p.getInfoAPI(p)
 

src/engines/engine/Properties.go

@@ -7,7 +7,8 @@ import (
 // Properties は各翻訳エンジンの基本となる構造体です.
 // 翻訳エンジンが API を呼び出すのに必要な基本情報と、翻訳に使われるメソッド（クラス関数）を持った構造体です.
 type Properties struct {
-	Cache *cache.TCache // 翻訳済みのテキストをキャッシュするためのオブジェクトのポインタです
+	// 翻訳済みのテキストをキャッシュするためのオブジェクトのポインタです
+	Cache *cache.TCache
 
 	// translate メソッドは、翻訳エンジンがインスタンス作成時に割り当てた関数です.
 	// inputText を langFrom から langTo  翻訳した結果を返します。この値はキャッシュされません.
@@ -17,10 +18,18 @@ type Properties struct {
 	// アクセス・トークンのアカウント情報のうち、AccountInfo 型の情報だけ返します.
 	getInfoAPI func(properties *Properties) (AccountInfo, error)
 
-	NameVarEnvAPIKey string // 環境変数からアクセス・トークンを取得する際の環境変数名
-	apiKey           string // 自動翻訳 API 用のアクセス・トークン（API キー）です。空の場合は環境変数から取得します。
+	// 環境変数からアクセス・トークンを取得する際の環境変数名
+	NameVarEnvAPIKey string
 
-	TimeInterval  int  // 1 リクエストごとに sleep させる秒数です（デフォルト: 1）
-	IsAccountFree bool // アクセス・トークンが無料アカウントの場合は true、有料アカウントの場合は false にセットします。（デフォルト: true）
-	Update        bool // true の場合はキャッシュを更新します。false の場合はなるべくキャッシュを使います（デフォルト: false）
+	// 自動翻訳 API 用のアクセス・トークン（API キー）です。空の場合は環境変数から取得します。
+	apiKey string
+
+	// 1 リクエストごとに sleep させる秒数です（デフォルト: 1）
+	TimeInterval int
+
+	// アクセス・トークンが無料アカウントの場合は true、有料アカウントの場合は false にセットします。（デフォルト: true）
+	IsAccountFree bool
+
+	// true の場合はキャッシュを更新します。false の場合はなるべくキャッシュを使います（デフォルト: false）
+	Update bool
 }