src/model/mdoc.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 of model entities
  16 module mdoc
  17
  18 import model_base
  19 import location
  20
  21 # Structured documentation of a `MEntity` object
  22 class MDoc
  23         # Raw content, line by line
  24         # The starting `#` and first space are stripped.
  25         # The trailing `\n` are chomped.
  26         var content = new Array[String]
  27
  28         # The entity where the documentation is originally attached to.
  29         # This gives some context to resolve identifiers or to run examples.
  30         var original_mentity: nullable MEntity = null is writable
  31
  32         # The original location of the doc for error messages
  33         var location: Location
  34
  35         # The comment first line
  36         var synopsis: String is lazy do return content.first
  37
  38         # All comment lines except for the synopsis
  39         var comment: String is lazy do
  40                 var lines = content.to_a
  41                 if not lines.is_empty then lines.shift
  42                 return lines.join("\n")
  43         end
  44
  45         # Full comment
  46         var documentation: String is lazy do return content.join("\n")
  47 end
  48
  49 redef class MEntity
  50         # The documentation associated to the entity
  51         var mdoc: nullable MDoc = null is writable
  52
  53         # The documentation associated to the entity or their main nested entity.
  54         #
  55         # * `MPackage`s fall back to their root `MGroup`.
  56         # * `MGroup`s fall back to their `default_mmodule`.
  57         # * `MClass`es, `MClassDef`s, `MProperty`s and `MPropDef`s fall-back to
  58         #   their introducing definition.
  59         # * `MClassType`s fall back to their wrapped `MClass`.
  60         # * `MVirtualType`s fall back to their wrapped `MProperty`.
  61         # * `CallSite` fall back on the wrapped `MProperty`.
  62         # * Other entities do not fall back.
  63         #
  64         # One may use `MDoc::original_mentity` to retrieve the original
  65         # source of the documentation.
  66         fun mdoc_or_fallback: nullable MDoc do return mdoc
  67
  68         # Is the entity deprecated?
  69         #
  70         # Used for warnings and in documentation.
  71         # Has no other specific effect.
  72         var deprecation: nullable MDeprecationInfo = null is writable
  73 end
  74
  75 # Information about a deprecated entity
  76 class MDeprecationInfo
  77         # Explanation about the deprecation
  78         var mdoc: nullable MDoc = null is writable
  79 end