Repository: NethermindEth/juno
Pull request #274 (2022-07-07 02:09:03)

Update database documentation
## Changes:
- Update database code documentation
- Documentation is able with the `godoc` tool

## Types of changes

What types of changes does your code introduce?

- Documentation Update

## Testing
**Requires testing**

- No


codecov[bot]: # [Codecov](https://codecov.io/gh/NethermindEth/juno/pull/274?src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=NethermindEth) Report
> Merging [#274](https://codecov.io/gh/NethermindEth/juno/pull/274?src=pr&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=NethermindEth) (468c911) into [main](https://codecov.io/gh/NethermindEth/juno/commit/8e4cfd276d0aa5780383ceff927d8d05fe2a0a5a?el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=NethermindEth) (8e4cfd2) will **not change** coverage.
> The diff coverage is `n/a`.

```diff
@@            Coverage Diff            @@
##              main      #274   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           65        65           
  Lines         5916      5919    +3     
=========================================
+ Hits          5916      5919    +3     
```

| Flag | Coverage Δ | |
|---|---|---|
| unittests | `100.00% <ø> (ø)` | |

Flags with carried forward coverage won't be shown. [Click here](https://docs.codecov.io/docs/carryforward-flags?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=NethermindEth#carryforward-flags-in-the-pull-request-comment) to find out more.

| [Impacted Files](https://codecov.io/gh/NethermindEth/juno/pull/274?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=NethermindEth) | Coverage Δ | |
|---|---|---|
| [internal/db/mdbx.go](https://codecov.io/gh/NethermindEth/juno/pull/274/diff?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=NethermindEth#diff-aW50ZXJuYWwvZGIvbWRieC5nbw==) | `100.00% <ø> (ø)` | |
| [internal/db/mdbx\_env.go](https://codecov.io/gh/NethermindEth/juno/pull/274/diff?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=NethermindEth#diff-aW50ZXJuYWwvZGIvbWRieF9lbnYuZ28=) | `100.00% <ø> (ø)` | |
| [pkg/crypto/weierstrass/weierstrass.go](https://codecov.io/gh/NethermindEth/juno/pull/274/diff?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=NethermindEth#diff-cGtnL2NyeXB0by93ZWllcnN0cmFzcy93ZWllcnN0cmFzcy5nbw==) | `100.00% <0.00%> (ø)` | |

------

[Continue to review full report at Codecov](https://codecov.io/gh/NethermindEth/juno/pull/274?src=pr&el=continue&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=NethermindEth).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=NethermindEth)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/NethermindEth/juno/pull/274?src=pr&el=footer&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=NethermindEth). Last update [8e4cfd2...468c911](https://codecov.io/gh/NethermindEth/juno/pull/274?src=pr&el=lastupdated&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=NethermindEth). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=NethermindEth).


Patch:
diff --git a/internal/db/doc.go b/internal/db/doc.go
new file mode 100644
index 00000000..97c9d51e
--- /dev/null
+++ b/internal/db/doc.go
@@ -0,0 +1,9 @@
+// Package db provides a simple interface to a database. The base behavior is described by the DatabaseOperations,
+// Database and DatabaseTransactional interfaces, any database implementation that match with these interfaces can be
+// used as a Juno database.
+//
+// Juno uses MDBX as its current database implementation. MDBX has a global environment (the database file) and within
+// it a group of isolated named databases. The environment is initialized with the InitializeMDBXEnv function, then
+// databases can be created with the NewMDBXDatabase function, an MDBXDatabse is a named database within the
+// initialized environment. If the database already exists, the database is opened, otherwise, it is created.
+package db
diff --git a/internal/db/mdbx.go b/internal/db/mdbx.go
index dcef4f0a..641d650b 100644
--- a/internal/db/mdbx.go
+++ b/internal/db/mdbx.go
@@ -17,8 +17,7 @@ var (
 	ErrTx = errors.New("transaction error")
 )
 
-// MDBXDatabase is a Database that works with the LMDB database. A database is a
-// named database (isolated collection stored on the same file) of a certain
+// MDBXDatabase is a named database (isolated collection stored on the same file) of a certain
 // environment (database file). One environment can have many named databases.
 // The environment must be initialized and configured with the correct number of
 // named databases before creating the MDBXDatabase instances.
@@ -27,7 +26,9 @@ type MDBXDatabase struct {
 	dbi mdbx.DBI
 }
 
-// NewMDBXDatabase creates a new MDBXDatabase with the given environment and name.
+// NewMDBXDatabase creates a new MDBXDatabase instance with the given environment
+// and name. If the environment does not have a named database with the given
+// name, it is created and returned, otherwise the existing database is returned.
 func NewMDBXDatabase(env *mdbx.Env, name string) (*MDBXDatabase, error) {
 	var dbi mdbx.DBI
 	// Start a READ transaction
diff --git a/internal/db/mdbx_env.go b/internal/db/mdbx_env.go
index d00e8e76..30130dae 100644
--- a/internal/db/mdbx_env.go
+++ b/internal/db/mdbx_env.go
@@ -11,9 +11,9 @@ var (
 	initialized bool
 )
 
-var ErrEnvNoInitialized = errors.New("environment is no initialize")
+var ErrEnvNotInitialized = errors.New("environment is not initialized")
 
-// InitializeMDBXEnv initializes the Juno LMDB environment.
+// InitializeMDBXEnv initializes the Juno MDBX environment.
 func InitializeMDBXEnv(path string, optMaxDB uint64, flags uint) (err error) {
 	defer func() {
 		if err == nil {
@@ -25,6 +25,7 @@ func InitializeMDBXEnv(path string, optMaxDB uint64, flags uint) (err error) {
 	return err
 }
 
+// NewMDBXEnv creates a new MDBX environment.
 func NewMDBXEnv(path string, optMaxDB uint64, flags uint) (*mdbx.Env, error) {
 	env, err := mdbx.NewEnv()
 	if err != nil {
@@ -49,11 +50,11 @@ func NewMDBXEnv(path string, optMaxDB uint64, flags uint) (*mdbx.Env, error) {
 	return env, nil
 }
 
-// GetMDBXEnv returns the Juno LMDB environment. If the environment is not
-// initialized then ErrEnvNoInitialized is returned.
+// GetMDBXEnv returns the Juno MDBX environment. If the environment is not initialized then ErrEnvNotInitialized is
+// returned.
 func GetMDBXEnv() (*mdbx.Env, error) {
 	if !initialized {
-		return nil, ErrEnvNoInitialized
+		return nil, ErrEnvNotInitialized
 	}
 	return env, nil
 }


Test patch:
diff --git a/internal/db/mdbx_test.go b/internal/db/mdbx_test.go
index 3bccc467..7b2e5653 100644
--- a/internal/db/mdbx_test.go
+++ b/internal/db/mdbx_test.go
@@ -187,8 +187,8 @@ func TestGetMDBXEnv(t *testing.T) {
 	env = nil
 	initialized = false
 	_, err := GetMDBXEnv()
-	if !errors.Is(err, ErrEnvNoInitialized) {
-		t.Errorf("expected ErrEnvNoInitialized error")
+	if !errors.Is(err, ErrEnvNotInitialized) {
+		t.Errorf("expected ErrEnvNotInitialized error")
 	}
 	err = InitializeMDBXEnv(t.TempDir(), 1, 0)
 	if err != nil {