src/doc/doc_model.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 # Nitdoc model template parts generation
  16 module doc_model
  17
  18 import model_utils
  19 import modelize_property
  20 import markdown
  21 import doc_templates
  22
  23 redef class MDoc
  24         # Comment synopsys HTML escaped
  25         fun short_comment: String do return content.first.html_escape
  26
  27         # Full comment HTML escaped
  28         fun full_comment: String do return content.join("\n").html_escape
  29
  30         # Synopsys in a template
  31         fun tpl_short_comment: Streamable do return short_markdown
  32
  33         # Full comment in a template
  34         fun tpl_comment: Streamable do return full_markdown
  35 end
  36
  37 redef class Location
  38         # Github url based on this location
  39         fun github(gitdir: String): String do
  40                 var base_dir = getcwd.join_path(gitdir).simplify_path
  41                 var file_loc = getcwd.join_path(file.filename).simplify_path
  42                 var gith_loc = file_loc.substring(base_dir.length + 1, file_loc.length)
  43                 return "{gith_loc}:{line_start},{column_start}--{line_end},{column_end}"
  44         end
  45 end
  46
  47 redef class MEntity
  48         # HTML Escaped name
  49         fun nitdoc_name: String is abstract
  50
  51         # HTML anchor to this entity in a nitdoc page
  52         fun nitdoc_anchor: String is abstract
  53
  54         # URL of this entity Nitdoc page
  55         fun nitdoc_url: String is abstract
  56
  57         # A template link to the mentity `nitdoc_anchor`
  58         fun tpl_anchor: TplLink is abstract
  59
  60         # A template link to the mentity `nitdoc_url`
  61         fun tpl_link: TplLink is abstract
  62
  63         # A template signature that contains modifiers and parameters
  64         fun tpl_declaration: Template is abstract
  65
  66         # A template namespace
  67         fun tpl_namespace: Template is abstract
  68
  69         # A template definition of the mentity
  70         # include name, sysnopsys, comment and namespace
  71         fun tpl_definition: TplDefinition is abstract
  72 end
  73
  74 redef class MProject
  75         fun nitdoc_mdoc: nullable MDoc do
  76                 if mdoc != null then return mdoc
  77                 if root == null then return null
  78                 if root.mdoc != null then return root.mdoc
  79                 if not root.mmodules.is_empty then return root.mmodules.first.mdoc
  80                 return null
  81         end
  82
  83         redef fun nitdoc_name do return name.html_escape
  84         redef fun nitdoc_anchor do return "PRJ_{nitdoc_name}"
  85
  86         redef fun nitdoc_url do
  87                 if root != null and not root.mmodules.is_empty then return root.mmodules.first.nitdoc_url
  88                 return "project_{name}.html"
  89         end
  90
  91         redef fun tpl_anchor do
  92                 var tpl = new TplLink("#{nitdoc_anchor}", nitdoc_name)
  93                 var mdoc = nitdoc_mdoc
  94                 if mdoc != null then
  95                         tpl.title = mdoc.short_comment
  96                 end
  97                 return tpl
  98         end
  99
 100         redef fun tpl_link do
 101                 var tpl = new TplLink(nitdoc_url, nitdoc_name)
 102                 var mdoc = nitdoc_mdoc
 103                 if mdoc != null then
 104                         tpl.title = mdoc.short_comment
 105                 end
 106                 return tpl
 107         end
 108
 109         redef fun tpl_declaration do
 110                 var tpl = new Template
 111                 tpl.add "<span>project "
 112                 tpl.add tpl_link
 113                 tpl.add "</span>"
 114                 return tpl
 115         end
 116
 117         redef fun tpl_namespace do return tpl_link
 118
 119         redef fun tpl_definition do
 120                 var tpl = new TplDefinition
 121                 tpl.namespace = tpl_namespace
 122                 var mdoc = nitdoc_mdoc
 123                 if mdoc != null then
 124                         tpl.comment = mdoc.tpl_comment
 125                 end
 126                 return tpl
 127         end
 128
 129         fun tpl_article: TplArticle do
 130                 var article = new TplArticle.with_title(nitdoc_anchor, tpl_link)
 131                 article.title_classes.add "signature"
 132                 article.subtitle = tpl_declaration
 133                 article.summary_title = nitdoc_name
 134                 article.content = tpl_definition
 135                 return article
 136         end
 137 end
 138
 139 redef class MGroup
 140         redef fun tpl_link do return mmodules.first.tpl_link
 141
 142         redef fun tpl_namespace do
 143                 if mproject == null then return tpl_link
 144                 if mproject.root != self then
 145                         var tpl = new Template
 146                         tpl.add mproject.tpl_namespace
 147                         tpl.add "::"
 148                         tpl.add self.tpl_link
 149                         return tpl
 150                 else
 151                         return mproject.tpl_namespace
 152                 end
 153         end
 154 end
 155
 156 redef class MModule
 157         # Is the mmodule created by nitdoc for internal purpose?
 158         var is_fictive: Bool writable = false
 159
 160         # Full namespace of this module
 161         fun full_namespace: String do
 162                 if public_owner != null then
 163                         return "{public_owner.nitdoc_name}::{nitdoc_name}"
 164                 end
 165                 return nitdoc_name
 166         end
 167
 168         redef fun nitdoc_name do return name.html_escape
 169
 170         redef fun nitdoc_url do
 171                 var res = new FlatBuffer
 172                 res.append("module_")
 173                 var mowner = public_owner
 174                 if mowner != null then
 175                         res.append("{public_owner.name}_")
 176                 end
 177                 res.append("{self.name}.html")
 178                 return res.to_s
 179         end
 180
 181         redef fun nitdoc_anchor: String do
 182                 var res = new FlatBuffer
 183                 res.append("MOD_")
 184                 var mowner = public_owner
 185                 if mowner != null then
 186                         res.append("{public_owner.nitdoc_name}_")
 187                 end
 188                 res.append(nitdoc_name)
 189                 return res.to_s
 190         end
 191
 192         redef fun tpl_anchor do
 193                 var tpl = new TplLink("#{nitdoc_anchor}", nitdoc_name)
 194                 if mdoc != null then
 195                         tpl.title = mdoc.short_comment
 196                 end
 197                 return tpl
 198         end
 199
 200         redef fun tpl_link do
 201                 var tpl = new TplLink(nitdoc_url, nitdoc_name)
 202                 if mdoc != null then
 203                         tpl.title = mdoc.short_comment
 204                 end
 205                 return tpl
 206         end
 207
 208         redef fun tpl_declaration do
 209                 var tpl = new Template
 210                 tpl.add "<span>module "
 211                 tpl.add tpl_namespace
 212                 tpl.add "</span>"
 213                 return tpl
 214         end
 215
 216         redef fun tpl_namespace do
 217                 var tpl = new Template
 218                 if mgroup != null and mgroup.mmodules.first != self then
 219                         tpl.add mgroup.tpl_namespace
 220                         tpl.add "::"
 221                 end
 222                 tpl.add "<span>"
 223                 tpl.add tpl_link
 224                 tpl.add "</span>"
 225                 return tpl
 226         end
 227
 228         redef fun tpl_definition do
 229                 var tpl = new TplDefinition
 230                 tpl.namespace = tpl_namespace
 231                 if mdoc != null then
 232                         tpl.comment = mdoc.tpl_comment
 233                 end
 234                 return tpl
 235         end
 236
 237         fun tpl_article: TplArticle do
 238                 var article = new TplArticle.with_title(nitdoc_anchor, tpl_link)
 239                 article.title_classes.add "signature"
 240                 article.subtitle = tpl_declaration
 241                 article.summary_title = nitdoc_name
 242                 article.content = tpl_definition
 243                 return article
 244         end
 245
 246         fun tpl_list_item: TplListItem do
 247                 var lnk = new Template
 248                 lnk.add tpl_link
 249                 if mdoc != null then
 250                         lnk.add ": "
 251                         lnk.add mdoc.short_comment
 252                 end
 253                 return new TplListItem.with_content(lnk)
 254         end
 255 end
 256
 257 redef class MClass
 258         redef fun nitdoc_name do return name.html_escape
 259         redef fun nitdoc_url do return "class_{public_owner}_{name}.html"
 260         redef fun nitdoc_anchor do return "CLASS_{public_owner.nitdoc_name}_{nitdoc_name}"
 261
 262         redef fun tpl_anchor do
 263                 var tpl = new TplLink("#{nitdoc_anchor}", nitdoc_name)
 264                 if intro.mdoc != null then
 265                         tpl.title = intro.mdoc.short_comment
 266                 end
 267                 return tpl
 268         end
 269
 270         redef fun tpl_link do
 271                 var tpl = new TplLink(nitdoc_url, nitdoc_name)
 272                 if intro.mdoc != null then
 273                         tpl.title = intro.mdoc.short_comment
 274                 end
 275                 return tpl
 276         end
 277
 278         redef fun tpl_declaration do return intro.tpl_declaration
 279
 280         redef fun tpl_namespace do
 281                 var tpl = new Template
 282                 tpl.add intro_mmodule.tpl_namespace
 283                 tpl.add "::<span>"
 284                 tpl.add tpl_link
 285                 tpl.add "</span>"
 286                 return tpl
 287         end
 288
 289         fun tpl_list_item: TplListItem do
 290                 var lnk = new Template
 291                 lnk.add tpl_link
 292                 if intro.mdoc != null then
 293                         lnk.add ": "
 294                         lnk.add intro.mdoc.short_comment
 295                 end
 296                 return new TplListItem.with_content(lnk)
 297         end
 298
 299         fun tpl_signature: Template do
 300                 var tpl = new Template
 301                 if arity > 0 then
 302                         tpl.add "["
 303                         tpl.add intro.parameter_names.join(", ")
 304                         tpl.add "]"
 305                 end
 306                 return tpl
 307         end
 308 end
 309
 310 redef class MClassDef
 311         redef fun nitdoc_name do return mclass.nitdoc_name
 312
 313         redef fun tpl_link do return mclass.tpl_link
 314
 315         redef fun tpl_namespace do
 316                 var tpl = new Template
 317                 tpl.add mmodule.tpl_namespace
 318                 tpl.add "::<span>"
 319                 tpl.add mclass.tpl_link
 320                 tpl.add "</span>"
 321                 return tpl
 322         end
 323
 324         redef fun tpl_declaration do
 325                 var tpl = new Template
 326                 tpl.add tpl_modifiers
 327                 tpl.add tpl_link
 328                 tpl.add tpl_signature
 329                 return tpl
 330         end
 331
 332         fun tpl_signature: Template do
 333                 var tpl = new Template
 334                 if not parameter_names.is_empty then
 335                         tpl.add "["
 336                         for i in [0..parameter_names.length[ do
 337                                 tpl.add "{parameter_names[i]}: "
 338                                 tpl.add bound_mtype.arguments[i].tpl_signature
 339                                 if i < parameter_names.length - 1 then tpl.add ", "
 340                         end
 341                         tpl.add "]"
 342                 end
 343                 return tpl
 344         end
 345
 346         redef fun tpl_definition do
 347                 var tpl = new TplClassDefinition
 348                 tpl.namespace = tpl_namespace
 349                 if mdoc != null then
 350                         tpl.comment = mdoc.tpl_comment
 351                 end
 352                 return tpl
 353         end
 354
 355         fun tpl_css_classes: Set[String] do
 356                 var set = new HashSet[String]
 357                 if is_intro then set.add "intro"
 358                 set.add_all mclass.intro.modifiers
 359                 set.add_all modifiers
 360                 return set
 361         end
 362
 363         fun tpl_modifiers: Template do
 364                 var tpl = new Template
 365                 for modifier in modifiers do
 366                         if modifier == "public" then continue
 367                         tpl.add "{modifier} "
 368                 end
 369                 return tpl
 370         end
 371 end
 372
 373 redef class MProperty
 374         redef fun nitdoc_name do return name.html_escape
 375
 376         redef fun tpl_namespace do
 377                 var tpl = new Template
 378                 tpl.add intro_mclassdef.mclass.tpl_namespace
 379                 tpl.add "::<span>"
 380                 tpl.add intro.tpl_link
 381                 tpl.add "</span>"
 382                 return tpl
 383         end
 384
 385         redef fun tpl_declaration do return intro.tpl_declaration
 386
 387         fun tpl_signature: Template do return new Template
 388 end
 389
 390 redef class MPropDef
 391         redef fun nitdoc_url do return "{mclassdef.mclass.nitdoc_url}#{nitdoc_anchor}"
 392
 393         redef fun nitdoc_anchor do
 394                 return "PROP_{mclassdef.mclass.public_owner.nitdoc_name}_{mproperty.name.to_cmangle}"
 395         end
 396
 397         redef fun tpl_anchor do
 398                 var tpl = new TplLink("#{nitdoc_anchor}", mproperty.nitdoc_name)
 399                 if mproperty.intro.mdoc != null then
 400                         tpl.title = mproperty.intro.mdoc.short_comment
 401                 end
 402                 return tpl
 403         end
 404
 405         redef fun tpl_link do
 406                 var tpl = new TplLink(nitdoc_url, mproperty.nitdoc_name)
 407                 if mproperty.intro.mdoc != null then
 408                         tpl.title = mproperty.intro.mdoc.short_comment
 409                 end
 410                 return tpl
 411         end
 412
 413         redef fun tpl_namespace do
 414                 var tpl = new Template
 415                 tpl.add mclassdef.tpl_namespace
 416                 tpl.add "::"
 417                 tpl.add mproperty.name
 418                 return tpl
 419         end
 420
 421         redef fun tpl_definition do
 422                 var tpl = new TplDefinition
 423                 tpl.namespace = mclassdef.tpl_namespace
 424                 if mdoc != null then
 425                         tpl.comment = mdoc.tpl_comment
 426                 end
 427                 return tpl
 428         end
 429
 430         redef fun tpl_declaration do
 431                 var tpl = new Template
 432                 tpl.add tpl_modifiers
 433                 tpl.add tpl_link
 434                 tpl.add tpl_signature
 435                 return tpl
 436         end
 437
 438         fun tpl_css_classes: Set[String] do
 439                 var set = new HashSet[String]
 440                 if is_intro then set.add "intro"
 441                 set.add_all mproperty.intro.modifiers
 442                 set.add_all modifiers
 443                 return set
 444         end
 445
 446         fun tpl_modifiers: Template do
 447                 var tpl = new Template
 448                 for modifier in modifiers do
 449                         if modifier == "public" then continue
 450                         tpl.add "{modifier} "
 451                 end
 452                 return tpl
 453         end
 454
 455         fun tpl_signature: Template do return new Template
 456 end
 457
 458 redef class MMethod
 459         redef fun tpl_signature do
 460                 var tpl = new Template
 461                 var params = new Array[String]
 462                 for param in intro.msignature.mparameters do
 463                         params.add param.name
 464                 end
 465                 if not params.is_empty then
 466                         tpl.add "("
 467                         tpl.add params.join(", ")
 468                         tpl.add ")"
 469                 end
 470                 return tpl
 471         end
 472 end
 473
 474 redef class MMethodDef
 475         redef fun tpl_signature do return msignature.tpl_signature
 476 end
 477
 478 redef class MVirtualTypeProp
 479         redef fun tpl_link do return mvirtualtype.tpl_link
 480         redef fun tpl_signature do return tpl_link
 481 end
 482
 483 redef class MVirtualTypeDef
 484         redef fun tpl_signature do
 485                 var tpl = new Template
 486                 tpl.add ": "
 487                 tpl.add bound.tpl_signature
 488                 return tpl
 489         end
 490 end
 491
 492 redef class MType
 493         fun tpl_signature: Template is abstract
 494 end
 495
 496 redef class MClassType
 497         redef fun tpl_link do return mclass.tpl_link
 498         redef fun tpl_signature do return tpl_link
 499 end
 500
 501 redef class MNullableType
 502         redef fun tpl_signature do
 503                 var tpl = new Template
 504                 tpl.add "nullable "
 505                 tpl.add mtype.tpl_signature
 506                 return tpl
 507         end
 508 end
 509
 510 redef class MGenericType
 511         redef fun tpl_signature do
 512                 var tpl = new Template
 513                 tpl.add tpl_link
 514                 tpl.add "["
 515                 for i in [0..arguments.length[ do
 516                         tpl.add arguments[i].tpl_signature
 517                         if i < arguments.length - 1 then tpl.add ", "
 518                 end
 519                 tpl.add "]"
 520                 return tpl
 521         end
 522 end
 523
 524 redef class MParameterType
 525         redef fun tpl_link do
 526                 var name = mclass.intro.parameter_names[rank]
 527                 return new TplLink.with_title("{mclass.nitdoc_url}#FT_{name}", name, "formal type")
 528         end
 529         redef fun tpl_signature do return tpl_link
 530 end
 531
 532 redef class MVirtualType
 533         redef fun tpl_link do return mproperty.intro.tpl_link
 534         redef fun tpl_signature do return tpl_link
 535 end
 536
 537 redef class MSignature
 538         redef fun tpl_signature do
 539                 var tpl = new Template
 540                 if not mparameters.is_empty then
 541                         tpl.add "("
 542                         for i in [0..mparameters.length[ do
 543                                 tpl.add mparameters[i].tpl_signature
 544                                 if i < mparameters.length - 1 then tpl.add ", "
 545                         end
 546                         tpl.add ")"
 547                 end
 548                 if return_mtype != null then
 549                         tpl.add ": "
 550                         tpl.add return_mtype.tpl_signature
 551                 end
 552                 return tpl
 553         end
 554 end
 555
 556 redef class MParameter
 557         fun tpl_signature: Template do
 558                 var tpl = new Template
 559                 tpl.add "{name}: "
 560                 tpl.add mtype.tpl_signature
 561                 if is_vararg then tpl.add "..."
 562                 return tpl
 563         end
 564 end
 565