LaconicNetwork/cosmos-sdk
7
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 2 Wiki Activity

docs: Improve markdownlint configuration (#11104)

Browse Source 
## Description

Closes: #9404



---

### Author Checklist

*All items are required. Please add a note to the item if the item is not applicable and
please add links to any relevant follow up issues.*

I have...

- [x] included the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title
- [ ] added `!` to the type prefix if API or client breaking change
- [x] targeted the correct branch (see [PR Targeting](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#pr-targeting))
- [x] provided a link to the relevant issue or specification
- [ ] followed the guidelines for [building modules](https://github.com/cosmos/cosmos-sdk/blob/master/docs/building-modules)
- [ ] included the necessary unit and integration [tests](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#testing)
- [ ] added a changelog entry to `CHANGELOG.md`
- [ ] included comments for [documenting Go code](https://blog.golang.org/godoc)
- [ ] updated the relevant documentation or specification
- [x] reviewed "Files changed" and left comments if necessary
- [x] confirmed all CI checks have passed

### Reviewers Checklist

*All items are required. Please add a note if the item is not applicable and please add
your handle next to the items reviewed if you only reviewed selected items.*

I have...

- [ ] confirmed the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title
- [ ] confirmed `!` in the type prefix if API or client breaking change
- [ ] confirmed all author checklist items have been addressed 
- [ ] reviewed state machine logic
- [ ] reviewed API design and naming
- [ ] reviewed documentation is accurate
- [ ] reviewed tests and test coverage
- [ ] manually tested (if applicable)
This commit is contained in:
Julien Robert
2022-02-10 12:07:01 +00:00
committed by GitHub
parent b1f9a117f7
commit 58597139fa
212 changed files with 3792 additions and 3755 deletions
Download Patch File Download Diff File Expand all files Collapse all files
x/group/internal/orm/spec/01_table.md
+9 -9
View File
@@ -2,17 +2,17 @@
A table can be built given a `codec.ProtoMarshaler` model type, a prefix to access the underlying prefix store used to store table data as well as a `Codec` for marshalling/unmarshalling.
+++ https://github.com/cosmos/cosmos-sdk/blob/9f78f16ae75cc42fc5fe636bde18a453ba74831f/x/group/internal/orm/table.go#L24-L30
+++ <https://github.com/cosmos/cosmos-sdk/blob/9f78f16ae75cc42fc5fe636bde18a453ba74831f/x/group/internal/orm/table.go#L24-L30>
In the prefix store, entities should be stored by an unique identifier called `RowID` which can be based either on an `uint64` auto-increment counter, string or dynamic size bytes.
Regular CRUD operations can be performed on a table, these methods take a `sdk.KVStore` as parameter to get the table prefix store.
The `table` struct does not:
- enforce uniqueness of the `RowID`
- enforce prefix uniqueness of keys, i.e. not allowing one key to be a prefix
* enforce uniqueness of the `RowID`
* enforce prefix uniqueness of keys, i.e. not allowing one key to be a prefix
of another
- optimize Gas usage conditions
* optimize Gas usage conditions
The `table` struct is private, so that we only have custom tables built on top of it, that do satisfy these requirements.
`table` provides methods for exporting (using a [`PrefixScan` `Iterator`](03_iterator_pagination.md#iterator)) and importing genesis data. For the import to be successful, objects have to be aware of their primary key by implementing the [`PrimaryKeyed`](#primarykeyed) interface.
@@ -21,7 +21,7 @@ The `table` struct is private, so that we only have custom tables built on top o
`AutoUInt64Table` is a table type with an auto incrementing `uint64` ID.
+++ https://github.com/cosmos/cosmos-sdk/blob/9f78f16ae75cc42fc5fe636bde18a453ba74831f/x/group/internal/orm/auto_uint64.go#L11-L14
+++ <https://github.com/cosmos/cosmos-sdk/blob/9f78f16ae75cc42fc5fe636bde18a453ba74831f/x/group/internal/orm/auto_uint64.go#L11-L14>
It's based on the `Sequence` struct which is a persistent unique key generator based on a counter encoded using 8 byte big endian.
@@ -33,7 +33,7 @@ It's based on the `Sequence` struct which is a persistent unique key generator b
The model provided for creating a `PrimaryKeyTable` should implement the `PrimaryKeyed` interface:
+++ https://github.com/cosmos/cosmos-sdk/blob/9f78f16ae75cc42fc5fe636bde18a453ba74831f/x/group/internal/orm/primary_key.go#L28-L41
+++ <https://github.com/cosmos/cosmos-sdk/blob/9f78f16ae75cc42fc5fe636bde18a453ba74831f/x/group/internal/orm/primary_key.go#L28-L41>
`PrimaryKeyFields()` method returns the list of key parts for a given object.
The primary key parts can be []byte, string, and `uint64` types.
@@ -42,6 +42,6 @@ The primary key parts can be []byte, string, and `uint64` types.
Key parts, except the last part, follow these rules:
- []byte is encoded with a single byte length prefix
- strings are null-terminated
- `uint64` are encoded using 8 byte big endian.
* []byte is encoded with a single byte length prefix
* strings are null-terminated
* `uint64` are encoded using 8 byte big endian.
x/group/internal/orm/spec/02_secondary_index.md
+4 -4
View File
@@ -2,19 +2,19 @@
Secondary indexes can be used on `Indexable` [tables](01_table.md). Indeed, those tables implement the `Indexable` interface that provides a set of functions that can be called by indexes to register and interact with the tables, like callback functions that are called on entries creation, update or deletion to create, update or remove corresponding entries in the table secondary indexes.
+++ https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/types.go#L88-L92
+++ <https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/types.go#L88-L92>
## MultiKeyIndex
A `MultiKeyIndex` is an index where multiple entries can point to the same underlying object.
+++ https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/index.go#L25-L31
+++ <https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/index.go#L25-L31>
Internally, it uses an `Indexer` that manages the persistence of the index based on searchable keys and create/update/delete operations.
+++ https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/index.go#L15-L19
+++ <https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/index.go#L15-L19>
+++ https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/indexer.go#L15-L18
+++ <https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/indexer.go#L15-L18>
The currently used implementation of an `indexer`, `Indexer`, relies on an `IndexerFunc` that should be provided when instantiating the index. Based on the source object, this function returns one or multiple index keys as `[]interface{}`. Such secondary index keys should be bytes, string or `uint64` in order to be handled properly by the [key codec](01_table.md#key-codec) which defines specific encoding for those types.
In the index prefix store, the keys are built based on the source object's `RowID` and its secondary index key(s) using the key codec and the values are set as empty bytes.
x/group/internal/orm/spec/03_iterator_pagination.md
+4 -4
View File
@@ -6,15 +6,15 @@ Both [tables](01_table.md) and [secondary indexes](02_secondary_index.md) suppor
An `Iterator` allows iteration through a sequence of key value pairs.
+++ https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/types.go#L77-L83
+++ <https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/types.go#L77-L83>
Tables rely on a `typeSafeIterator` that is used by `PrefixScan` and `ReversePrefixScan` `table` methods to iterate through a range of `RowID`s.
+++ https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/table.go#235-L239
+++ <https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/table.go#235-L239>
Secondary indexes rely on an `indexIterator` that can strip the `RowID` from the full index key in order to get the underlying value in the table prefix store.
+++ https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/index.go#L227-L232
+++ <https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/index.go#L227-L232>
Under the hood, both use a prefix store `Iterator` (alias for tm-db `Iterator`).
@@ -23,6 +23,6 @@ Under the hood, both use a prefix store `Iterator` (alias for tm-db `Iterator`).
The `Paginate` function does pagination given an [`Iterator`](#iterator) and a `query.PageRequest`, and returns a `query.PageResponse`.
It unmarshals the results into the provided dest interface that should be a pointer to a slice of models.
+++ https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/iterator.go#L117-L216
+++ <https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/iterator.go#L117-L216>
Secondary indexes have a `GetPaginated` method that returns an `Iterator` for the given searched secondary index key, starting from the `query.PageRequest` key if provided. It's important to note that this `query.PageRequest` key should be a `RowID` (that could have been returned by a previous paginated request). The returned `Iterator` can then be used with the `Paginate` function and the same `query.PageRequest`.
x/group/internal/orm/spec/README.md
+6 -6
View File
@@ -5,11 +5,11 @@ The orm package provides a framework for creating relational database tables wit
## Contents
1. **[Table](01_table.md)**
- [AutoUInt64Table](01_table.md#autouint64table)
- [PrimaryKeyTable](01_table.md#primarykeytable)
* [AutoUInt64Table](01_table.md#autouint64table)
* [PrimaryKeyTable](01_table.md#primarykeytable)
2. **[Secondary Index](02_secondary_index.md)**
- [MultiKeyIndex](02_secondary_index.md#multikeyindex)
- [UniqueIndex](02_secondary_index.md#uniqueindex)
* [MultiKeyIndex](02_secondary_index.md#multikeyindex)
* [UniqueIndex](02_secondary_index.md#uniqueindex)
3. **[Iterator and Pagination](03_iterator_pagination.md)**
- [Iterator](03_iterator_pagination.md#iterator)
- [Pagination](03_iterator_pagination.md#pagination)
* [Iterator](03_iterator_pagination.md#iterator)
* [Pagination](03_iterator_pagination.md#pagination)