contrib/neo_doxygen/src/model/descriptions.nit

   1 # This file is part of NIT ( http://www.nitlanguage.org ).
   2 #
   3 # Licensed under the Apache License, Version 2.0 (the "License");
   4 # you may not use this file except in compliance with the License.
   5 # You may obtain a copy of the License at
   6 #
   7 # http://www.apache.org/licenses/LICENSE-2.0
   8 #
   9 # Unless required by applicable law or agreed to in writing, software
  10 # distributed under the License is distributed on an "AS IS" BASIS,
  11 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 # See the License for the specific language governing permissions and
  13 # limitations under the License.
  14
  15 # Documentation associated to an entity.
  16 module model::descriptions
  17
  18 import json::static
  19 import json
  20
  21 # Documentation associated to an entity.
  22 #
  23 # The documentation is written in Markdown format.
  24 #
  25 # ~~~nit
  26 # var doc = new Documentation
  27 #
  28 # doc.brief_description = "Do something."
  29 # doc.detailed_description = ["Do not lunch a rocket."]
  30 # assert doc.brief_description == "Do something."
  31 # assert doc.detailed_description == ["Do not lunch a rocket."]
  32 # assert doc.to_json == """["Do something.","Do not lunch a rocket."]"""
  33 #
  34 # doc.brief_description = ""
  35 # doc.detailed_description = ["The answer is `42`."]
  36 # assert doc.brief_description == "The answer is `42`."
  37 # assert doc.detailed_description == ["The answer is `42`."]
  38 # assert doc.to_json == """["The answer is `42`."]"""
  39 #
  40 # doc.detailed_description = ["The answer is `42`."]
  41 # doc.brief_description = ""
  42 # assert doc.brief_description == "The answer is `42`."
  43 # assert doc.detailed_description == ["The answer is `42`."]
  44 # assert doc.to_json == """["The answer is `42`."]"""
  45 #
  46 # doc.detailed_description = new Array[String]
  47 # doc.brief_description = ""
  48 # assert doc.is_empty
  49 # assert doc.brief_description == ""
  50 # assert doc.detailed_description == new Array[String]
  51 # assert doc.to_json == "[]"
  52 # ~~~
  53 class Documentation
  54         super Serializable
  55
  56         private var content = new JsonStringArray
  57         private var has_brief_description: Bool = false
  58
  59         # The brief description.
  60         #
  61         # If it is empty, the first element of `detailed_description` will be used
  62         # as brief description.
  63         fun brief_description=(brief_description: String) do
  64                 if brief_description.is_empty then
  65                         if has_brief_description then
  66                                 content.shift
  67                                 has_brief_description = false
  68                         end
  69                 else if has_brief_description then
  70                         content.first = brief_description
  71                 else
  72                         content.unshift(brief_description)
  73                         has_brief_description = true
  74                 end
  75         end
  76
  77         # The brief description.
  78         fun brief_description: String do
  79                 if not is_empty then return content.first
  80                 return ""
  81         end
  82
  83         # The detailed description.
  84         #
  85         # Each element should represent a block.
  86         fun detailed_description=(detailed_description: SequenceRead[String]) do
  87                 if has_brief_description then
  88                         while content.length > 1 do content.pop
  89                 else
  90                         content.clear
  91                 end
  92                 content.add_all(detailed_description)
  93         end
  94
  95         # The detailed description.
  96         #
  97         # Each element should represent a block.
  98         fun detailed_description: SequenceRead[String] do
  99                 if not has_brief_description then return content
 100                 if content.length > 1 then return content.subarray(1, content.length - 1)
 101                 return new Array[String]
 102         end
 103
 104         # Add a block of detailed description.
 105         fun add(block: String) do content.add block
 106
 107         # Is the documentation empty?
 108         fun is_empty: Bool do return content.is_empty
 109
 110         redef fun serialize_to(v) do content.serialize_to v
 111         redef fun accept_json_serializer(v) do content.serialize_to v
 112 end
 113
 114 # A `Serializable` array of strings.
 115 private class JsonStringArray
 116         super JsonSequenceRead[String]
 117         super Array[String]
 118 end