From 6ad93ef4f7467ec5b461bc518715247a3cdd9b56 Mon Sep 17 00:00:00 2001 From: "Xinwei Xiong (cubxxw)" <3293172751nss@gmail.com> Date: Tue, 19 Mar 2024 17:04:15 +0800 Subject: [PATCH] build: make lint format code --- docs/contrib/go-doc.md | 93 +++++++++++++----------------------------- 1 file changed, 28 insertions(+), 65 deletions(-) diff --git a/docs/contrib/go-doc.md b/docs/contrib/go-doc.md index 1304d55d8..65b88514e 100644 --- a/docs/contrib/go-doc.md +++ b/docs/contrib/go-doc.md @@ -1,87 +1,50 @@ -# go doc +# Go Language Documentation for OpenIM -Go语言项目十分重视代码的文档，在软件设计中，文档对于软件的可维护和易使用具有重大的影响。因此，文档必须是书写良好并准确的，与此同时它还需要易于书写和维护。 +In the realm of software development, especially within Go language projects, documentation plays a crucial role in ensuring code maintainability and ease of use. Properly written and accurate documentation is not only essential for understanding and utilizing software effectively but also needs to be easy to write and maintain. This principle is at the heart of OpenIM's approach to supporting commands and generating documentation. +## Supported Commands in OpenIM -**OpenIM 支持的命令 +OpenIM leverages Go language's documentation standards to facilitate clear and maintainable code documentation. Below are some of the key commands used in OpenIM for documentation purposes: -Go语言注释 -Go语言中注释一般分为两种，分别是单行注释和多行注释 +### `go doc` Command -单行注释是以 // 开头的注释，可以出现在任何地方。 -多行注释也叫块注释，以 /* 开头，以 */ 结尾，不可以嵌套使用，一般用于包的文档描述或注释成块的代码片段。 -每一个 package 都应该有相关注释，在 package 语句之前的注释内容将被默认认为是这个包的文档， package 的注释应该提供一些相关信息并对整体功能做简要的介绍。 +The `go doc` command is used to print documentation for Go language entities such as variables, constants, functions, structures, and interfaces. This command allows specifying the identifier of the program entity to tailor the output. Examples of `go doc` command usage include: -在日常开发过程中，可以使用go doc和godoc命令生成代码的文档。 +- `go doc sync.WaitGroup.Add` prints the documentation for a specific method of a type in a package. +- `go doc -u -all sync.WaitGroup` displays all program entities, including unexported ones, for a specified type. +- `go doc -u sync` outputs all program entities for a specified package, focusing on exported ones without detailed comments. +### `godoc` Command +For environments lacking internet access, the `godoc` command serves to view the Go language standard library and project dependency library documentation in a web format. Notably, post-Go 1.12 versions, `godoc` is not part of the Go compiler suite. It can be installed using: -go doc -go doc 命令打印Go语言程序实体上的文档。可以使用参数来指定程序实体的标识符。 - -Go语言程序实体是指变量、常量、函数、结构体以及接口。 - -程序实体标识符就是程序实体的名称。 - -输出指定 package ，指定类型，指定方法的注释 - -$ go doc sync.WaitGroup.Add -输出指定 package ，指定类型的所有程序实体，包括未导出的 - -$ go doc -u -all sync.WaitGroup - -输出指定 package 的所有程序实体（非所有详细注释） - -$ go doc -u sync - - -godoc -godoc命令主要用于在无法联网的环境下，以web形式，查看Go语言标准库和项目依赖库的文档。 - -在 go 1.12 之后的版本中，godoc不再做为go编译器的一部分存在。依然可以通过go get命令安装： - +```shell go get -u -v golang.org/x/tools/cmd/godoc -国内的安装方法 +``` +The `godoc` command, once running, hosts a local web server (by default on port 6060) to facilitate documentation browsing at http://127.0.0.1:6060. It generates documentation based on the GOROOT and GOPATH directories, showcasing both the project's own documentation and that of third-party packages installed via `go get`. -Explain -mkdir -p $GOPATH/src/golang.org/x -cd $GOPATH/src/golang.org/x -git clone https://github.com/golang/tools.git -cd tools/cmd/godoc -go install -ls -alh $GOPATH/bin -通过终端查看文档 +### Custom Documentation Generation Commands in OpenIM -go doc命令 +OpenIM includes a suite of commands aimed at initializing, generating, and maintaining project documentation and associated files. Some notable commands are: -$ go doc help -usage: go doc [-u] [-c] [package|[package.]symbol[.method]] -可以看到，go doc接受的参数，可以是包名，也可以是包里的结构、方法等，默认为显示当前目录下的文档。 +- `gen.init`: Initializes the OpenIM server project. +- `gen.docgo`: Generates missing `doc.go` files for Go packages, crucial for package-level documentation. +- `gen.errcode.doc`: Generates markdown documentation for OpenIM error codes. +- `gen.ca`: Generates CA files for all certificates, enhancing security documentation. +These commands underscore the project's commitment to thorough and accessible documentation, supporting both developers and users alike. -通过网页查看文档 +## Writing Your Own Documentation -godoc命令 +When creating documentation for Go projects, including OpenIM, it's important to follow certain practices: -$ godoc -http=:6060 -godoc会监听6060端口，通过网页访问 http://127.0.0.1:6060，godoc基于GOROOT和GOPATH路径下的代码生成文档的。打开首页如下，我们自己项目工程文档和通过go get的代码文档都在Packages中的Third party里面。 +1. **Commenting**: Use single-line (`//`) and block (`/* */`) comments to provide detailed documentation within the code. Block comments are especially useful for package documentation, which should immediately precede the package statement without any intervening blank lines. +2. **Overview Section**: To create an overview section in the documentation, place a block comment directly before the package statement. This section should succinctly describe the package's purpose and functionality. +3. **Detailed Descriptions**: Comments placed before functions, structures, or variables will be used to generate detailed descriptions in the documentation. Follow the same commenting rules as for the overview section. -编写自己的文档 +4. **Examples**: Include example functions prefixed with `Example` to demonstrate usage. Output from these examples can be documented at the end of the function, starting with `// Output:` followed by the expected result. -1、设计接口函数代码 - -创建documents/calc.go文件 - - -编写文档规则 - -1、文档中显示的详细主体内容，大多是由用户注释部分提供，注释的方式有两种，单行注释"//"和代码块"/* */"注释。 - -2、在源码文件中，在package语句前做注释，在文档中看到的就是Overview部分， 注意：此注释必须紧挨package语句前一行，要作为Overview部分的，注释块中间不能有空行。 - -3、在函数、结构、变量等前做注释的，在文档中看到的就是该项详细描述。注释规则同上。 - -4、编写的Example程序，函数名必须以Example为前缀，可将测试的输出结果放在在函数尾部，以"// Output:"另起一行，然后将输出内容注释，并追加在后面。 \ No newline at end of file +Through adherence to these documentation practices, OpenIM ensures that its codebase remains accessible, maintainable, and easy to use for developers and users alike. \ No newline at end of file