Kotlin - Detailed Kotlin a text document

Author: opLW

table of Contents

1. The document used tags
2.Kotlin java different from the document
application 3.Markdown document in Kotlin

1.Kotlin document commonly used tags

• 1.1 commonly used tags

  label	effect	Special Precautions
  @constructor description	Introduce primary constructor	Only for class
  @author author	Introduction Author
  @since version	Describes the current class or method which version generated in
  @param Parameter Name Description	Describes the parameters	You can use the "[]" and the name of the parameter spaced Description
  @see <identifier>	References to other classes or methods	After adding the identifier as described in the document will not be written
  @sample <identifier>	Examples of how to use the current method or class	After adding the identifier as described in the document will not be written
  @receiver <Identifier> Description	Recipient introduction spread function	Identifier needs described using "[]" symbol enclosed, the added effective
  @throws exception name describes, @ exception abnormal Name Description	To remind the user to note abnormal	Two contents of the label, when generating the document would be attributed to a class: Throws
  @suppress	Elements that do not require written documentation but requires publicly, use @suppress	This element has not been written notes document file
  @Deprecated	Indicates that the current class or outdated methods
  @return description	Introduction return value

• 1.2 Example

  /**
   *   @constructor 构建一个Kdoc测试类
   *   @author opLW
   *   @date  2020/2/7
   *   @since 0.0.1
   */
  class LabelTest() {
  
   /**
    * [我是一个链接][com.oplw.test.kdoc.MarkdownTest.testTitle]
    *
    * `我是代码段`
    *
    * [我是超链接](https://baidu.com)
    * 
    * @param i 传进来的参数为i
    * @see com.oplw.test.kdoc.MarkdownTest.testTitle
    * @sample com.oplw.test.kdoc.MarkdownTest.testTitle
    * @throws MyException 当i小于0时抛出异常
    * @exception MyException 当i小于0时抛出异常
    * @return 返回值为整型
    */
    fun testFun(i: Int): Int {
       if (i < 0) {
           throw MyException("The value of i is smaller than 0")
       }
       return i
    }
  
    inner class MyException(errorMsg: String): Exception(errorMsg)
  }
  
  /**
   * @receiver [com.oplw.test.kdoc.MarkdownTest.testTitle] 我是一个扩展函数
   */
  fun LabelTest.extentsion() {  }
  

• 1.3 @Throws difference @throws labels and annotations previously mentioned @throws tags for the document, Kotlin there a @throws annotation for improving interoperability and Java.

  • Background in Java abnormalities will be seized and abnormal non abnormal categories will be seized. But Kotlin Unlike Java, Kotlin no abnormalities must be inspected , that is not necessary to use try ... catch to catch exceptions; no need to declare the exceptions thrown, even when derived from Java classes, do not have to declare method throws an exception. But if you want to capture or throw is also possible.
  • Effect when used in a Java class may throw an exception Kotlin method, the method for adding @Throws (SomeException :: class) notes, so in Java can (and need to) handle the exception.
  • 参考文章 throws Exception in a method with Kotlin

2.Kotlin with java documentation part of the difference

• 2.1 chaining documents often need to refer to other elements, you can quickly access to other related content via links

  • Java Java is linked to the use of @linkspecific use as follows:

    /**
     * 链接方式一：{@link test#testBlock()}
     * <p>链接方式二：{@link com.oplw.test.test#testBlock()}</p>
     */
    

    @linkIt requires the use of complex symbols {}. Can be a single line, it may be interspersed among the other text;

  • Kotlin KDoc inlining @link tag instead of
    the format : [description text link] [class or method]

    /**
    * [这是一个链接][com.oplw.test.kdoc.MarkdownTest.testTitle]
    */
    

    Above to Kotlinlink the way, to note that:

    • Wherein the link text description may be omitted
    • When using a fully qualified class name of the expression, Kotlin use. "" Code division assembly, while Java using the "#" (also true elsewhere)

• 2.2 hyperlinks way Java to use htmlformat, Kotlinuse markdowmformat

  // Java
   /**
    * @see <a href="http://baidu.com">描述链接的文字</a>
    */
    
  // Kotlin   
   /**
    * [描述链接的文字](https://baidu.com)
    */
  

• 2.3 document code document enabled code pattern, code and general text differentiate.

  // Java
   /**
    * {@code java}
    */
   
  // Kotlin   
   /**
    * `Kotlin`
    */
  

  As shown in the above code. JavaUsed @codelabels, Kotlinthe use of anti-quotes (English input method, Escthe bottom of the bond)
• Differences 2.4 text format Kotlin introduction Markdownwritten text, talk separately below.

Application 3.Markdown in Kotlin document

• 3.1 were tested as will be commonly applied to each Markdown syntax process

  class MarkdownTest {
   /**
    * **1.使用 = 和 - 标记一级和二级标题**
    *
    * 我展示的是一级标题
    * =================
    *
    * 我展示的是二级标题
    * -----------------
    *
    * **2.使用 # 号标记**
    *
    * # 一级标题
    * ## 二级标题
    * ### 三级标题
    * #### 四级标题
    * ##### 五级标题
    * ###### 六级标题
    */
   fun testTitle() {}
   
   ......省略其他方法
  }
  

• 3.2 Test Results

  • In Android Studio effects of grammar more, not one posted
    
    
  • Results in a document file in the same section posted
    
    

• 3.3 summary

  Valid syntax	Invalid syntax
  Use "#" and change its number to create a multi-level title	Use "=====" or "------" to create a multi-level heading
  By "empty line" to wrap	Use "~ ~ ~ ~ text" Create strikethrough
  Use "*" or "_" and change the number of the font weight adjustment, inclination	Use "<u> text </ u>" underline text
  Use "-" to create a multilevel list	Use "text == ==" add color to text
  A production code using backticks	Use ">" Create block
  Making use of three successive code blocks single quotes	image link
  Link [link description text] (URL) format	Create a table of symbols

Love and passion, men do not bother mercy.
Should speak there is nothing wrong, the end of the text message informed me,
Should felt that I could, like the collection point to be together.
opLW original seven poems, please indicate the source