Home | History | Annotate | Download | only in elements 
      1 /*
      2  * Copyright (C) 2017 The Android Open Source Project
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 package writer.elements
     18 
     19 import lexer.TokenGrammar
     20 import parser.config
     21 import parser.elements.EntryParser
     22 import parser.elements.declarations.ArgEntry
     23 import parser.elements.declarations.MethodDeclarationParser
     24 import writer.formatTextasHTML
     25 import writer.htmlEscape
     26 import writer.warn
     27 import java.text.ParseException
     28 
     29 class MethodElement(parser: EntryParser) : AbstractElement(parser) {
     30     override val declarationParser = parser.declarationParser as MethodDeclarationParser
     31 
     32     //prefix, params, returns
     33     override fun declaration(): String {
     34         val sb = StringBuilder()
     35         declarationParser.prefix?.let { sb.append("${it} ") }
     36         sb.append("${declarationParser.name} (")
     37         declarationParser.params.forEachIndexed { i, arg ->
     38             sb.append(htmlEscape("${arg.type} ${arg.name}"))
     39             if (i < declarationParser.params.size-1) sb.append(", ")
     40         }
     41         sb.append(")")
     42         if (declarationParser.returns.isNotEmpty()) {
     43             sb.append("\ngenerates (")
     44             declarationParser.returns.forEachIndexed { i, arg ->
     45                 sb.append(htmlEscape("${arg.type} ${arg.name}"))
     46                 if (i < declarationParser.returns.size-1) sb.append(", ")
     47             }
     48             sb.append(")")
     49         }
     50         return sb.toString()
     51     }
     52 
     53     override fun detailsRows(): String {
     54         return """
     55 ${buildPrefixRows()}
     56 ${buildParamRows()}
     57 ${buildReturnRows()}
     58 """.trim()
     59     }
     60 
     61     private fun getDocAnnotationDesc(tag: TokenGrammar, arg: ArgEntry): String {
     62         return docParser.docAnnotationParsers
     63                 .filter { it.tag == tag }
     64                 .firstOrNull { it.arg == arg.name }
     65                 ?.let { formatTextasHTML(it.description, useParagraphs = false) }
     66                 ?: run {
     67             val msg = "Missing @${tag.value} doc annotation for '${arg.type} ${arg.name}'"
     68             if (config.errorOnly) {
     69                 throw ParseException(msg, 0)
     70             } else {
     71                 warn(msg)
     72                 "" //return empty string if it can't find it
     73             }
     74         }
     75     }
     76 
     77     private fun buildPrefixRows(): String {
     78         val sb = StringBuilder()
     79         if (declarationParser.prefix != null) {
     80             sb.append("""
     81             <tr>
     82               <td>RPC mode</td>
     83               <td>
     84                 <table class="function param responsive">
     85                   <tbody>
     86                     <tr>
     87                       <td>
     88                         <code>${declarationParser.prefix}</code>
     89                       </td>
     90                     </tr>
     91                   </tbody>
     92                 </table>
     93               </td>
     94             </tr>""")
     95         }
     96         return sb.toString()
     97     }
     98 
     99     private fun buildParamRows(): String {
    100         //docParser.docAnnotationParsers //=> tag [TokenGrammer], arg?, description
    101         val sb = StringBuilder()
    102         if (declarationParser.params.isNotEmpty()) {
    103             sb.append("""
    104             <tr>
    105               <td>Parameters</td>
    106               <td>
    107                 <table class="function param responsive">
    108                   <tbody>""")
    109             declarationParser.params.forEach { arg ->
    110                 sb.append("""
    111                 <tr>
    112                   <td>
    113                     <code>${htmlEscape(arg.name)}</code>
    114                   </td>
    115                   <td>
    116                     <div>${getDocAnnotationDesc(TokenGrammar.PARAM, arg)}</div>
    117                   </td>
    118                 </tr>""")
    119             }
    120             sb.append("""
    121                   </tbody>
    122                 </table>
    123               </td>
    124             </tr>""")
    125         }
    126         return sb.toString()
    127     }
    128 
    129     private fun buildReturnRows(): String {
    130         val sb = StringBuilder()
    131         if (declarationParser.returns.isNotEmpty()) {
    132             sb.append("""
    133             <tr>
    134               <td>Generates</td>
    135               <td>
    136                 <table class="function param responsive">
    137                   <tbody>""")
    138             declarationParser.returns.forEach { arg ->
    139                 sb.append("""
    140                 <tr>
    141                   <td>
    142                     <code>${htmlEscape(arg.name)}</code>
    143                   </td>
    144                   <td>
    145                     <div>${getDocAnnotationDesc(TokenGrammar.RETURN, arg)}</div>
    146                   </td>
    147                 </tr>""")
    148             }
    149             sb.append("""
    150                   </tbody>
    151                 </table>
    152               </td>
    153             </tr>""")
    154         }
    155         return sb.toString()
    156     }
    157 }