move config description to godoc

longbridge · Jan 17, 2022 · a420a75 · a420a75
1 parent e55f3d4
commit a420a75
Show file tree

Hide file tree

Showing 3 changed files with 45 additions and 112 deletions.
diff --git a/README.md b/README.md
@@ -24,7 +24,9 @@ go get -u github.com/longbridgeapp/gorm-sharding
 
 After the database connection opened, use the sharding plugin that registered the tables which you want to shard.
 
-The `Register` function takes a map, the key is the **original table name** and the value is a **resolver** which is composed by five configurable fields that described in [Config description](#config-description).
+The `Register` function takes a map, the key is the **original table name** and the value is a **resolver** which is composed by five configurable fields.
+
+For config detail info, see [Godoc](https://pkg.go.dev/github.com/longbridge/gorm-sharding).
 
 ## Usage Example
 
@@ -52,58 +54,6 @@ middleware := sharding.Register(map[string]sharding.Resolver{
 db.Use(middleware)
 ```
 
-## Config description
-
-- [EnableFullTable](#EnableFullTable)
-- [ShardingColumn](#ShardingColumn)
-- [ShardingAlgorithm](#ShardingAlgorithm)
-- [ShardingAlgorithmByPrimaryKey](#ShardingAlgorithmByPrimaryKey)
-- [PrimaryKeyGenerate](#PrimaryKeyGenerate)
-
-#### EnableFullTable
-
-Whether to enable a full table.
-
-When full table enabled, sharding plugin will double write data to both main table and sharding table.
-
-#### ShardingColumn
-
-Which table column you want to used for sharding the table rows.
-
-For example, for a product order table, you may want to split the rows by `user_id`.
-
-### ShardingAlgorithm
-
-A function to generate the sharding table's suffix by the column value.
-
-It's signature is `func(columnValue interface{}) (suffix string, err error)`.
-
-For an example, see the [usage example](#usage-example) above.
-
-#### ShardingAlgorithmByPrimaryKey
-
-A function to generate the sharding table's suffix by the primary key.
-
-It's signature is `func(id int64) (suffix string)`.
-
-For an example, see the [usage example](#usage-example) above.
-
-Note, when the record contains an id field, ShardingAlgorithmByPrimaryKey will preferred than ShardingAlgorithm.
-
-#### PrimaryKeyGenerate
-
-A function to generate the primary key.
-
-Used only when insert and the record does not contains an id field.
-
-It's signature is `func(tableIdx int64) int64`.
-
-For an example, see the [usage example](#usage-example) above.
-
-We recommend you use the [keygen](https://github.com/longbridgeapp/gorm-sharding/tree/main/keygen) component, it is a distributed primary key generator.
-
-When use auto-increment like generator, the tableIdx argument could ignored.
-
 ## License
 
 This project under MIT license.
diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -24,7 +24,9 @@ go get -u github.com/longbridgeapp/gorm-sharding
 
 数据库连接打开后，使用分表插件注册需要拆分的表。
 
-`Register` 函数接收一个 map，键是**原始表名**，值是一个 **resolver** ，由可配置的字段组成，见配置描述。
+`Register` 函数接收一个 map，键是**原始表名**，值是一个 **resolver** ，由可配置的字段组成。
+
+具体配置信息见 [Godoc](https://pkg.go.dev/github.com/longbridge/gorm-sharding)。
 
 ## 用法示例
 
@@ -52,59 +54,6 @@ middleware := sharding.Register(map[string]sharding.Resolver{
 db.Use(middleware)
 ```
 
-## 配置描述
-
-- [EnableFullTable](#EnableFullTable)
-- [ShardingColumn](#ShardingColumn)
-- [ShardingAlgorithm](#ShardingAlgorithm)
-- [ShardingAlgorithmByPrimaryKey](#ShardingAlgorithmByPrimaryKey)
-- [PrimaryKeyGenerate](#PrimaryKeyGenerate)
-
-#### EnableFullTable
-
-Whether to enable a full table.
-是否开启全表。
-
-开启后，分表插件将双写数据到主表和分表。
-
-#### ShardingColumn
-
-用来分表的表字段。
-
-如，对于一个订单表，你可能想用 `user_id` 拆分数据。
-
-### ShardingAlgorithm
-
-使用列值生成分表后缀的函数。
-
-签名是 `func(columnValue interface{}) (suffix string, err error)`。
-
-可以参考上面的用法示例。
-
-#### ShardingAlgorithmByPrimaryKey
-
-使用主键生成分表后缀的函数。
-
-签名是 `func(id int64) (suffix string)`。
-
-可以参考上面的用法示例。
-
-注意，当记录包含 id 字段时，ShardingAlgorithmByPrimaryKey 优先于 ShardingAlgorithm。
-
-#### PrimaryKeyGenerate
-
-生成主键的函数。
-
-只有当插入数据并且记录不包含 id 字段时使用。
-
-签名是 `func(tableIdx int64) int64`。
-
-可以参考上面的用法示例。
-
-推荐使用 [keygen](https://github.com/longbridgeapp/gorm-sharding/tree/main/keygen) 组件，它是一个分布式的主键生成器。
-
-当使用自增类的生成器时，tableIdx 参数可以忽略。
-
 ## 许可证
 
 本项目使用 MIT 许可证。
diff --git a/sharding.go b/sharding.go
@@ -24,15 +24,49 @@ type Sharding struct {
 }
 
 type Resolver struct {
-	// EnableFullTable whether to enable a full table
+	// EnableFullTable represents whether to enable full table.
+	// When enabled, data will double write to both main table and sharding table.
 	EnableFullTable bool
-	// ShardingColumn column name of the sharding column, for example: user_id
+
+	// ShardingColumn specifies the table column you want to used for sharding the table rows.
+	// For example, for a product order table, you may want to split the rows by `user_id`.
 	ShardingColumn string
-	// ShardingAlgorithm implement the sharding algorithm for generate table name suffix
+
+	// ShardingAlgorithm specifies a function to generate the sharding
+	// table's suffix by the column value.
+	// For example, this function implements a mod sharding algorithm.
+	//
+	// 	func(value interface{}) (suffix string, err error) {
+	//		if uid, ok := value.(int64);ok {
+	//			return fmt.Sprintf("_%02d", user_id % 64), nil
+	//		}
+	//		return "", errors.New("invalid user_id")
+	// 	}
 	ShardingAlgorithm func(columnValue interface{}) (suffix string, err error)
-	// ShardingAlgorithm sharding algorithm by primary key, if it posible.
+
+	// ShardingAlgorithmByPrimaryKey specifies a function to generate the sharding
+	// table's suffix by the primary key.
+	// Note, when the record contains an id field,
+	// ShardingAlgorithmByPrimaryKey will preferred than ShardingAlgorithm.
+	// For example, this function use the Keygen library to generate the suffix.
+	//
+	// 	func(id int64) (suffix string) {
+	//		return fmt.Sprintf("_%02d", keygen.TableIdx(id))
+	//	}
 	ShardingAlgorithmByPrimaryKey func(id int64) (suffix string)
-	// PrimaryKeyGenerate for generate primary key
+
+	// PrimaryKeyGenerate specifies a function to generate the primary key.
+	// Used only when insert and the record does not contains an id field.
+	// We recommend you use the
+	// [keygen](https://github.com/longbridgeapp/gorm-sharding/tree/main/keygen) component,
+	// it is a distributed primary key generator.
+	// When use auto-increment like generator, the tableIdx argument could ignored.
+	//
+	// For example, this function use the Keygen library to generate the primary key.
+	//
+	// 	func(tableIdx int64) int64 {
+	//		return keygen.Next(tableIdx)
+	//	}
 	PrimaryKeyGenerate func(tableIdx int64) int64
 }