Merge remote-tracking branch 'upstream/main'

mosn · Oct 28, 2021 · b3a9740 · b3a9740
2 parents 0b07491 + 2007e1d
commit b3a9740
Show file tree

Hide file tree

Showing 8 changed files with 195 additions and 3 deletions.
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
@@ -66,6 +66,7 @@
   - [Component Development Guide](en/development/developing-component.md)
   - You wanna modify proto files or API definition?
     - [Development specification when adding API](en/development/developing-api.md)
+    - [Comment specification of proto file](en/api_reference/comment_spec_of_proto.md)
     - [How to generate API document based on the proto files](en/api_reference/how_to_generate_api_doc.md)
   - [Explanation for github workflow](en/development/explanation-for-github-workflow.md)
   - [Layotto contributor guide](en/development/CONTRIBUTING.md)

diff --git a/docs/en/api_reference/comment_spec_of_proto.md b/docs/en/api_reference/comment_spec_of_proto.md
@@ -0,0 +1,42 @@
+
+# Comment specification of proto file
+
+Avoid adding empty lines between comments  symbols `//`.If there is a blank line in the comments, the tool(protoc-gen-doc) will generate malformed documents.
+bad case:
+```
+message  BadCase{
+  // XXXXXXXX
+  //
+  // XX
+  //
+  // XXXXXX
+  field A
+}
+```
+good case:
+```
+message  GoodCase{
+  // XXXXXXXX
+  // XX
+  // XXXXXX
+  field A
+}
+```
+Or you can use another annotation symbol directly `/*  */`
+
+
+If you want to have some comment in your proto files, but don't want them to be part of the docs, you can simply prefix the comment with `@exclude`.
+Example: include only the comment for the id field
+```
+/**
+ * @exclude
+ * This comment won't be rendered
+ */
+message ExcludedMessage {
+  string id   = 1; // the id of this message.
+  string name = 2; // @exclude the name of this message
+
+  /* @exclude the value of this message. */
+  int32 value = 3;
+}
+```
diff --git a/docs/en/development/explanation-for-github-workflow.md b/docs/en/development/explanation-for-github-workflow.md
@@ -54,6 +54,10 @@ docker run -it --rm -v $(pwd):/github/workspace apache/skywalking-eyes header fi
 
 It will add license headers for code files recursively.
 
+##### How to configurate the License checker to ignore files of specified types?
+The ignore list is in `.licenserc.yaml`. You can add new types into it.
+
+##### For more details of this tool
 See https://github.com/marketplace/actions/license-eye#docker-image for details
 
 #### TODO: PR title lint

diff --git a/docs/zh/_sidebar.md b/docs/zh/_sidebar.md
@@ -72,6 +72,7 @@
     - [组件开发指南](zh/development/developing-component.md)
     - 想要修改proto文件或API定义？
         - [新增API时的开发规范](zh/development/developing-api.md)
+        - [proto文件注释规范](zh/api_reference/comment_spec_of_proto.md)
         - [如何基于proto文件生成接口文档](zh/api_reference/how_to_generate_api_doc.md)  
     - [Layotto贡献者指南](zh/development/CONTRIBUTING.md) 
     - [解释一下Layotto的github workflow](zh/development/explanation-for-github-workflow.md)

diff --git a/docs/zh/api_reference/comment_spec_of_proto.md b/docs/zh/api_reference/comment_spec_of_proto.md
@@ -0,0 +1,41 @@
+
+# proto文件注释规范
+
+避免在注释符号`//`之间添加空行，否则生成工具protoc-gen-doc会生成格式错乱的文档。
+一个坏示例:
+```
+message  BadCase{
+  // XXXXXXXX
+  //
+  // XX
+  //
+  // XXXXXX
+  field A
+}
+```
+一个好示例:
+```
+message  GoodCase{
+  // XXXXXXXX
+  // XX
+  // XXXXXX
+  field A
+}
+```
+或者你可以直接使用另一种注释符号:`/*  */`
+
+假如你想添加一些注释在proto文件里，但不想让它们出现在生成的文档里，你可以在注释里使用`@exclude`前缀。
+示例：只包括id字段的注释
+```
+/**
+ * @exclude
+ * This comment won't be rendered
+ */
+message ExcludedMessage {
+  string id   = 1; // the id of this message.
+  string name = 2; // @exclude the name of this message
+
+  /* @exclude the value of this message. */
+  int32 value = 3;
+}
+```
diff --git a/docs/zh/api_reference/how_to_generate_api_doc.md b/docs/zh/api_reference/how_to_generate_api_doc.md
@@ -1,7 +1,9 @@
-# How to generate api documents
+# 如何基于proto文件生成接口文档
+
+
+我们可以用[protoc-gen-doc](https://github.com/pseudomuto/protoc-gen-doc) 和docker来生成接口文档，相关命令如下：  
+(需要在layotto项目下运行命令)
 
-We can use [protoc-gen-doc](https://github.com/pseudomuto/protoc-gen-doc) and docker to generate api documents,the command is as follows:  
-(Run in layotto directory)
 ```
 docker run --rm \
 -v  $(pwd)/docs/en/api_reference:/out \

diff --git a/docs/zh/development/explanation-for-github-workflow.md b/docs/zh/development/explanation-for-github-workflow.md
@@ -54,6 +54,10 @@ docker run -it --rm -v $(pwd):/github/workspace apache/skywalking-eyes header fi
 
 It will add license headers for code files recursively.
 
+##### How to configurate the License checker to ignore files of specified types?
+The ignore list is in `.licenserc.yaml`. You can add new types into it.
+
+##### For more details of this tool
 See https://github.com/marketplace/actions/license-eye#docker-image for details
 
 #### TODO: PR title lint

diff --git a/sdk/java-sdk/pom.xml b/sdk/java-sdk/pom.xml
@@ -8,6 +8,10 @@
     <version>1.0.0-SNAPSHOT</version>
     <packaging>pom</packaging>
 
+    <name>runtime-sdk-parent</name>
+    <description>SDK for Runtime</description>
+    <url>https://github.com/mosn/layotto</url>
+
     <modules>
         <module>sdk</module>
         <module>examples</module>
@@ -97,4 +101,97 @@
         </plugins>
     </build>
 
+    <licenses>
+        <license>
+            <name>The Apache License, Version 2.0</name>
+            <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
+        </license>
+    </licenses>
+
+    <developers>
+        <developer>
+            <name>seeflood</name>
+            <email>349895584@qq.com</email>
+            <organization>MOSN</organization>
+            <organizationUrl>https://mosn.io/</organizationUrl>
+        </developer>
+        <developer>
+            <name>MentosL</name>
+            <email>1367654518@qq.com</email>
+            <organization>MOSN</organization>
+            <organizationUrl>https://mosn.io/</organizationUrl>
+        </developer>
+        <developer>
+            <name>ZLBer</name>
+            <email>1098294815@qq.com</email>
+            <organization>MOSN</organization>
+            <organizationUrl>https://mosn.io/</organizationUrl>
+        </developer>
+        <developer>
+            <name>kevinten10</name>
+            <organizationUrl>http://www.kevinten.com/</organizationUrl>
+        </developer>
+    </developers>
+
+    <scm>
+        <url>http://github.com/mosn/layotto</url>
+        <connection>scm:git:https://github.com/mosn/layotto.git</connection>
+    </scm>
+    <profiles>
+        <profile>
+            <id>release</id>
+            <build>
+                <plugins>
+                    <plugin>
+                        <groupId>org.apache.maven.plugins</groupId>
+                        <artifactId>maven-javadoc-plugin</artifactId>
+                        <version>2.10.4</version>
+                        <executions>
+                            <execution>
+                                <id>attach-javadocs</id>
+                                <goals>
+                                    <goal>jar</goal>
+                                </goals>
+                            </execution>
+                        </executions>
+                    </plugin>
+                    <plugin>
+                        <groupId>org.sonatype.plugins</groupId>
+                        <artifactId>nexus-staging-maven-plugin</artifactId>
+                        <version>1.6.7</version>
+                        <extensions>true</extensions>
+                        <configuration>
+                            <serverId>ossrh</serverId>
+                            <nexusUrl>https://s01.oss.sonatype.org/</nexusUrl>
+                            <autoReleaseAfterClose>false</autoReleaseAfterClose>
+                        </configuration>
+                    </plugin>
+                    <plugin>
+                        <groupId>org.apache.maven.plugins</groupId>
+                        <artifactId>maven-gpg-plugin</artifactId>
+                        <version>1.6</version>
+                        <executions>
+                            <execution>
+                                <id>sign-artifacts</id>
+                                <phase>verify</phase>
+                                <goals>
+                                    <goal>sign</goal>
+                                </goals>
+                            </execution>
+                        </executions>
+                    </plugin>
+                </plugins>
+            </build>
+            <distributionManagement>
+                <snapshotRepository>
+                    <id>ossrh</id>
+                    <url>https://s01.oss.sonatype.org/content/repositories/snapshots</url>
+                </snapshotRepository>
+                <repository>
+                    <id>ossrh</id>
+                    <url>https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/</url>
+                </repository>
+            </distributionManagement>
+        </profile>
+    </profiles>
 </project>