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
  20 # Documentation associated to an entity.
  21 #
  22 # The documentation is written in Markdown format.
  23 #
  24 # ~~~nit
  25 # var doc = new Documentation
  26 #
  27 # doc.brief_description = "Do something."
  28 # doc.detailed_description = ["Do not lunch a rocket."]
  29 # assert doc.brief_description == "Do something."
  30 # assert doc.detailed_description == ["Do not lunch a rocket."]
  31 # assert doc.to_json == """["Do something.","Do not lunch a rocket."]"""
  32 #
  33 # doc.brief_description = ""
  34 # doc.detailed_description = ["The answer is `42`."]
  35 # assert doc.brief_description == "The answer is `42`."
  36 # assert doc.detailed_description == ["The answer is `42`."]
  37 # assert doc.to_json == """["The answer is `42`."]"""
  38 #
  39 # doc.detailed_description = ["The answer is `42`."]
  40 # doc.brief_description = ""
  41 # assert doc.brief_description == "The answer is `42`."
  42 # assert doc.detailed_description == ["The answer is `42`."]
  43 # assert doc.to_json == """["The answer is `42`."]"""
  44 #
  45 # doc.detailed_description = new Array[String]
  46 # doc.brief_description = ""
  47 # assert doc.is_empty
  48 # assert doc.brief_description == ""
  49 # assert doc.detailed_description == new Array[String]
  50 # assert doc.to_json == "[]"
  51 # ~~~
  52 class Documentation
  53         super Jsonable
  54
  55         private var content = new JsonStringArray
  56         private var has_brief_description: Bool = false
  57
  58         # The brief description.
  59         #
  60         # If it is empty, the first element of `detailed_description` will be used
  61         # as brief description.
  62         fun brief_description=(brief_description: String) do
  63                 if brief_description.is_empty then
  64                         if has_brief_description then
  65                                 content.shift
  66                                 has_brief_description = false
  67                         end
  68                 else if has_brief_description then
  69                         content.first = brief_description
  70                 else
  71                         content.unshift(brief_description)
  72                         has_brief_description = true
  73                 end
  74         end
  75
  76         # The brief description.
  77         fun brief_description: String do
  78                 if not is_empty then return content.first
  79                 return ""
  80         end
  81
  82         # The detailed description.
  83         #
  84         # Each element should represent a block.
  85         fun detailed_description=(detailed_description: SequenceRead[String]) do
  86                 if has_brief_description then
  87                         while content.length > 1 do content.pop
  88                 else
  89                         content.clear
  90                 end
  91                 content.add_all(detailed_description)
  92         end
  93
  94         # The detailed description.
  95         #
  96         # Each element should represent a block.
  97         fun detailed_description: SequenceRead[String] do
  98                 if not has_brief_description then return content
  99                 if content.length > 1 then return content.subarray(1, content.length - 1)
 100                 return new Array[String]
 101         end
 102
 103         # Add a block of detailed description.
 104         fun add(block: String) do content.add block
 105
 106         # Is the documentation empty?
 107         fun is_empty: Bool do return content.is_empty
 108
 109         redef fun to_json do return content.to_json
 110         redef fun append_json(b) do content.append_json(b)
 111 end
 112
 113 # A `Jsonable` array of strings.
 114 private class JsonStringArray
 115         super JsonSequenceRead[String]
 116         super Array[String]
 117 end