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 markdown
  20 import doc_templates
  21 import ordered_tree
  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         # Used as HTML unique ids
  52         fun nitdoc_id: 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 do
  59                 var tpl = new TplLink("#{nitdoc_id}", nitdoc_name)
  60                 if mdoc != null then
  61                         tpl.title = mdoc.short_comment
  62                 end
  63                 return tpl
  64         end
  65
  66         # A template link to the mentity `nitdoc_url`
  67         fun tpl_link: TplLink do
  68                 var tpl = new TplLink(nitdoc_url, nitdoc_name)
  69                 if mdoc != null then
  70                         tpl.title = mdoc.short_comment
  71                 end
  72                 return tpl
  73         end
  74
  75         # A template article that briefly describe the entity
  76         fun tpl_short_article: TplArticle do
  77                 var tpl = tpl_article
  78                 if mdoc != null then
  79                         tpl.content = mdoc.tpl_short_comment
  80                 end
  81                 return tpl
  82         end
  83
  84         # A template article that describe the entity
  85         fun tpl_article: TplArticle do
  86                 var tpl = new TplArticle.with_title(nitdoc_id, tpl_title)
  87                 tpl.title_classes.add "signature"
  88                 tpl.subtitle = tpl_namespace
  89                 tpl.summary_title = nitdoc_name
  90                 return tpl
  91         end
  92
  93         # A template signature that contains modifiers and parameters
  94         fun tpl_declaration: Template is abstract
  95
  96         # A template namespace
  97         fun tpl_namespace: Template is abstract
  98
  99         # A template definition of the mentity
 100         # include name, sysnopsys, comment and namespace
 101         fun tpl_definition: TplDefinition is abstract
 102
 103         # A li element that can go in a list
 104         fun tpl_list_item: TplListItem do
 105                 var lnk = new Template
 106                 lnk.add new TplLabel.with_classes(tpl_css_classes)
 107                 lnk.add tpl_link
 108                 if mdoc != null then
 109                         lnk.add ": "
 110                         lnk.add mdoc.short_comment
 111                 end
 112                 return new TplListItem.with_content(lnk)
 113         end
 114
 115         fun tpl_css_classes: Array[String] is abstract
 116
 117         # Box title for this mentity
 118         fun tpl_title: Template do
 119                 var title = new Template
 120                 title.add tpl_icon
 121                 title.add tpl_namespace
 122                 return title
 123         end
 124
 125         # Icon that will be displayed before the title
 126         fun tpl_icon: TplIcon do
 127                 var icon = new TplIcon.with_icon("tag")
 128                 icon.css_classes.add_all(tpl_css_classes)
 129                 return icon
 130         end
 131 end
 132
 133 redef class MConcern
 134         # Return a li element for `self` that can be displayed in a concern list
 135         private fun tpl_concern_item: TplListItem do
 136                 var lnk = new Template
 137                 lnk.add tpl_anchor
 138                 if mdoc != null then
 139                         lnk.add ": "
 140                         lnk.add mdoc.short_comment
 141                 end
 142                 return new TplListItem.with_content(lnk)
 143         end
 144 end
 145
 146 redef class MProject
 147         redef fun nitdoc_name do return name.html_escape
 148         redef fun nitdoc_id do return nitdoc_name
 149         redef fun nitdoc_url do return root.nitdoc_url
 150
 151         redef fun mdoc do
 152                 if root != null then
 153                         return root.mdoc
 154                 end
 155                 return super
 156         end
 157
 158         redef fun tpl_declaration do
 159                 var tpl = new Template
 160                 tpl.add "<span>project "
 161                 tpl.add tpl_link
 162                 tpl.add "</span>"
 163                 return tpl
 164         end
 165
 166         redef fun tpl_namespace do return tpl_link
 167
 168         redef fun tpl_definition do
 169                 var tpl = new TplDefinition
 170                 if mdoc != null then
 171                         tpl.comment = mdoc.tpl_comment
 172                 end
 173                 return tpl
 174         end
 175
 176         redef fun tpl_css_classes do return ["public"]
 177 end
 178
 179 redef class MGroup
 180         redef fun nitdoc_name do return name.html_escape
 181
 182         redef fun nitdoc_id do
 183                 if parent != null then
 184                         return "{parent.nitdoc_id}__{nitdoc_name}"
 185                 end
 186                 return "{mproject.nitdoc_id}__{nitdoc_name}"
 187         end
 188
 189         redef fun nitdoc_url do return "group_{name}.html"
 190
 191         redef fun tpl_namespace do
 192                 var tpl = new Template
 193                 if mproject != null then
 194                         tpl.add mproject.tpl_namespace
 195                 else if parent != null then
 196                         tpl.add parent.tpl_namespace
 197                 end
 198                 if mproject != null and mproject.root != self then
 199                         tpl.add "::"
 200                         tpl.add tpl_link
 201                 end
 202                 return tpl
 203         end
 204
 205         redef fun tpl_declaration do
 206                 var tpl = new Template
 207                 tpl.add "<span>group "
 208                 tpl.add tpl_link
 209                 tpl.add "</span>"
 210                 return tpl
 211         end
 212
 213         redef fun tpl_definition do
 214                 var tpl = new TplDefinition
 215                 if mdoc != null then
 216                         tpl.comment = mdoc.tpl_comment
 217                 end
 218                 return tpl
 219         end
 220 end
 221
 222 redef class MModule
 223         redef fun nitdoc_name do return name.html_escape
 224
 225         redef fun nitdoc_id do
 226                 if mgroup != null then
 227                         return "{mgroup.nitdoc_id}__{nitdoc_name}"
 228                 end
 229                 return nitdoc_name
 230         end
 231
 232         redef fun nitdoc_url do
 233                 var res = new FlatBuffer
 234                 res.append("module_")
 235                 var mowner = public_owner
 236                 if mowner != null then
 237                         res.append("{public_owner.name}_")
 238                 end
 239                 res.append("{self.name}.html")
 240                 return res.to_s
 241         end
 242
 243         redef fun tpl_declaration do
 244                 var tpl = new Template
 245                 tpl.add "<span>module "
 246                 tpl.add tpl_link
 247                 tpl.add "</span>"
 248                 return tpl
 249         end
 250
 251         redef fun tpl_namespace do
 252                 var tpl = new Template
 253                 if mgroup != null then
 254                         tpl.add mgroup.tpl_namespace
 255                         tpl.add "::"
 256                 end
 257                 tpl.add tpl_link
 258                 return tpl
 259         end
 260
 261         redef fun tpl_definition do
 262                 var tpl = new TplClassDefinition
 263                 if mdoc != null then
 264                         tpl.comment = mdoc.tpl_comment
 265                 end
 266                 return tpl
 267         end
 268
 269         redef fun tpl_css_classes do return ["public"]
 270 end
 271
 272 redef class MClass
 273         redef fun nitdoc_name do return name.html_escape
 274         redef fun nitdoc_id do return "{intro_mmodule.mgroup.mproject}__{name.to_cmangle}"
 275         redef fun nitdoc_url do return "class_{public_owner}_{name}.html"
 276
 277         redef fun mdoc do return intro.mdoc
 278
 279         redef fun tpl_declaration do return intro.tpl_declaration
 280
 281         redef fun tpl_namespace do
 282                 var tpl = new Template
 283                 tpl.add intro_mmodule.mgroup.mproject.tpl_namespace
 284                 tpl.add "::<span>"
 285                 tpl.add tpl_link
 286                 tpl.add "</span>"
 287                 return tpl
 288         end
 289
 290         redef fun tpl_title do
 291                 var title = new Template
 292                 title.add tpl_icon
 293                 title.add tpl_link
 294                 title.add tpl_signature
 295                 return title
 296         end
 297
 298         redef fun tpl_icon do return intro.tpl_icon
 299
 300         fun tpl_signature: Template do
 301                 var tpl = new Template
 302                 if arity > 0 then
 303                         tpl.add "["
 304                         tpl.add intro.parameter_names.join(", ")
 305                         tpl.add "]"
 306                 end
 307                 return tpl
 308         end
 309
 310         redef fun tpl_article do
 311                 var tpl = super
 312                 tpl.summary_title = "{nitdoc_name}{tpl_signature.write_to_string}"
 313                 return tpl
 314         end
 315
 316         redef fun tpl_css_classes do return intro.tpl_css_classes
 317 end
 318
 319 redef class MClassDef
 320         redef fun nitdoc_name do return mclass.nitdoc_name
 321         redef fun nitdoc_id do return "{mmodule.nitdoc_id}__{name.to_cmangle}"
 322         redef fun nitdoc_url do return "{mclass.nitdoc_url}#{nitdoc_id}"
 323
 324         redef fun tpl_namespace do
 325                 var tpl = new Template
 326                 tpl.add mmodule.tpl_namespace
 327                 tpl.add "::<span>"
 328                 tpl.add mclass.tpl_link
 329                 tpl.add "</span>"
 330                 return tpl
 331         end
 332
 333         redef fun tpl_article do
 334                 var tpl = new TplArticle(nitdoc_id)
 335                 tpl.summary_title = "in {mmodule.nitdoc_name}"
 336                 tpl.title = tpl_declaration
 337                 tpl.title_classes.add "signature"
 338                 var title = new Template
 339                 title.add "in "
 340                 title.add mmodule.tpl_namespace
 341                 tpl.subtitle = title
 342                 if mdoc != null then
 343                         tpl.content = mdoc.tpl_comment
 344                 end
 345                 return tpl
 346         end
 347
 348         redef fun tpl_title do
 349                 var title = new Template
 350                 title.add tpl_icon
 351                 title.add tpl_link
 352                 title.add tpl_signature
 353                 return title
 354         end
 355
 356         redef fun tpl_declaration do
 357                 var tpl = new Template
 358                 tpl.add tpl_modifiers
 359                 tpl.add tpl_link
 360                 tpl.add tpl_signature
 361                 return tpl
 362         end
 363
 364         fun tpl_signature: Template do
 365                 var tpl = new Template
 366                 if not parameter_names.is_empty then
 367                         tpl.add "["
 368                         for i in [0..parameter_names.length[ do
 369                                 tpl.add "{parameter_names[i]}: "
 370                                 tpl.add bound_mtype.arguments[i].tpl_signature
 371                                 if i < parameter_names.length - 1 then tpl.add ", "
 372                         end
 373                         tpl.add "]"
 374                 end
 375                 return tpl
 376         end
 377
 378         redef fun tpl_definition do
 379                 var tpl = new TplClassDefinition
 380                 tpl.namespace = tpl_namespace
 381                 if mdoc != null then
 382                         tpl.comment = mdoc.tpl_comment
 383                 end
 384                 return tpl
 385         end
 386
 387         redef fun tpl_css_classes do
 388                 var set = new HashSet[String]
 389                 if is_intro then set.add "intro"
 390                 set.add_all mclass.intro.modifiers
 391                 set.add_all modifiers
 392                 return set.to_a
 393         end
 394
 395         fun tpl_modifiers: Template do
 396                 var tpl = new Template
 397                 for modifier in modifiers do
 398                         if modifier == "public" then continue
 399                         tpl.add "{modifier} "
 400                 end
 401                 return tpl
 402         end
 403
 404         redef fun tpl_list_item do
 405                 var lnk = new Template
 406                 lnk.add new TplLabel.with_classes(tpl_css_classes)
 407                 lnk.add tpl_link
 408                 if mdoc != null then
 409                         lnk.add ": "
 410                         lnk.add mdoc.short_comment
 411                 else if mclass.intro.mdoc != null then
 412                         lnk.add ": "
 413                         lnk.add mclass.intro.mdoc.short_comment
 414                 end
 415                 return new TplListItem.with_content(lnk)
 416         end
 417
 418         redef fun tpl_anchor: TplLink do
 419                 var tpl = new TplLink("#{nitdoc_id}", nitdoc_name)
 420                 if mdoc != null then
 421                         tpl.title = mdoc.short_comment
 422                 else if mclass.intro.mdoc != null then
 423                         tpl.title = mclass.intro.mdoc.short_comment
 424                 end
 425                 return tpl
 426         end
 427
 428         redef fun tpl_link: TplLink do
 429                 var tpl = new TplLink(nitdoc_url, nitdoc_name)
 430                 if mdoc != null then
 431                         tpl.title = mdoc.short_comment
 432                 else if mclass.intro.mdoc != null then
 433                         tpl.title = mclass.intro.mdoc.short_comment
 434                 end
 435                 return tpl
 436         end
 437 end
 438
 439 redef class MProperty
 440         redef fun nitdoc_name do return name.html_escape
 441         redef fun nitdoc_id do return "{intro_mclassdef.mclass.nitdoc_id}__{name.to_cmangle}"
 442         redef fun nitdoc_url do return "proprety_{nitdoc_id}.html"
 443
 444         redef fun mdoc do return intro.mdoc
 445
 446         redef fun tpl_namespace do
 447                 var tpl = new Template
 448                 tpl.add intro_mclassdef.mclass.tpl_namespace
 449                 tpl.add "::<span>"
 450                 tpl.add intro.tpl_link
 451                 tpl.add "</span>"
 452                 return tpl
 453         end
 454
 455         redef fun tpl_declaration do return intro.tpl_declaration
 456
 457         fun tpl_signature: Template do return new Template
 458
 459         redef fun tpl_title do return intro.tpl_title
 460
 461         redef fun tpl_icon do return intro.tpl_icon
 462
 463         redef fun tpl_css_classes do return intro.tpl_css_classes
 464 end
 465
 466 redef class MPropDef
 467         redef fun nitdoc_name do return mproperty.nitdoc_name
 468         redef fun nitdoc_id do return "{mclassdef.nitdoc_id}__{name.to_cmangle}"
 469         redef fun nitdoc_url do return "{mproperty.nitdoc_url}#{nitdoc_id}"
 470
 471         redef fun tpl_anchor: TplLink do
 472                 var tpl = new TplLink("#{nitdoc_id}", nitdoc_name)
 473                 if mdoc != null then
 474                         tpl.title = mdoc.short_comment
 475                 else if mproperty.intro.mdoc != null then
 476                         tpl.title = mproperty.intro.mdoc.short_comment
 477                 end
 478                 return tpl
 479         end
 480
 481         redef fun tpl_link: TplLink do
 482                 var tpl = new TplLink(nitdoc_url, nitdoc_name)
 483                 if mdoc != null then
 484                         tpl.title = mdoc.short_comment
 485                 else if mproperty.intro.mdoc != null then
 486                         tpl.title = mproperty.intro.mdoc.short_comment
 487                 end
 488                 return tpl
 489         end
 490
 491         redef fun tpl_namespace do
 492                 var tpl = new Template
 493                 tpl.add mclassdef.tpl_namespace
 494                 tpl.add "::"
 495                 tpl.add mproperty.name
 496                 return tpl
 497         end
 498
 499         redef fun tpl_article do
 500                 var tpl = new TplArticle(nitdoc_id)
 501                 tpl.summary_title = "in {mclassdef.nitdoc_name}"
 502                 var title = new Template
 503                 title.add "in "
 504                 title.add mclassdef.tpl_link
 505                 tpl.title = title
 506                 tpl.subtitle = tpl_declaration
 507                 if mdoc != null then
 508                         tpl.content = mdoc.tpl_comment
 509                 end
 510                 return tpl
 511         end
 512
 513         redef fun tpl_title do
 514                 var title = new Template
 515                 title.add tpl_icon
 516                 title.add tpl_link
 517                 title.add tpl_signature
 518                 return title
 519         end
 520
 521         redef fun tpl_definition do
 522                 var tpl = new TplDefinition
 523                 tpl.namespace = mclassdef.tpl_namespace
 524                 if mdoc != null then
 525                         tpl.comment = mdoc.tpl_comment
 526                 end
 527                 return tpl
 528         end
 529
 530         redef fun tpl_declaration do
 531                 var tpl = new Template
 532                 tpl.add tpl_modifiers
 533                 tpl.add tpl_link
 534                 tpl.add tpl_signature
 535                 return tpl
 536         end
 537
 538         redef fun tpl_css_classes do
 539                 var set = new HashSet[String]
 540                 if is_intro then set.add "intro"
 541                 set.add_all mproperty.intro.modifiers
 542                 set.add_all modifiers
 543                 return set.to_a
 544         end
 545
 546         fun tpl_modifiers: Template do
 547                 var tpl = new Template
 548                 for modifier in modifiers do
 549                         if modifier == "public" then continue
 550                         tpl.add "{modifier} "
 551                 end
 552                 return tpl
 553         end
 554
 555         fun tpl_signature: Template do return new Template
 556
 557         redef fun tpl_list_item do
 558                 var lnk = new Template
 559                 lnk.add new TplLabel.with_classes(tpl_css_classes.to_a)
 560                 lnk.add tpl_link
 561                 if mdoc != null then
 562                         lnk.add ": "
 563                         lnk.add mdoc.short_comment
 564                 else if mproperty.intro.mdoc != null then
 565                         lnk.add ": "
 566                         lnk.add mproperty.intro.mdoc.short_comment
 567                 end
 568                 return new TplListItem.with_content(lnk)
 569         end
 570 end
 571
 572 redef class MMethod
 573         redef fun tpl_signature do
 574                 var tpl = new Template
 575                 var params = new Array[String]
 576                 for param in intro.msignature.mparameters do
 577                         params.add param.name
 578                 end
 579                 if not params.is_empty then
 580                         tpl.add "("
 581                         tpl.add params.join(", ")
 582                         tpl.add ")"
 583                 end
 584                 return tpl
 585         end
 586 end
 587
 588 redef class MMethodDef
 589         redef fun tpl_signature do return msignature.tpl_signature
 590 end
 591
 592 redef class MVirtualTypeProp
 593         redef fun tpl_link do return mvirtualtype.tpl_link
 594         redef fun tpl_signature do return tpl_link
 595 end
 596
 597 redef class MVirtualTypeDef
 598         redef fun tpl_signature do
 599                 var tpl = new Template
 600                 tpl.add ": "
 601                 tpl.add bound.tpl_signature
 602                 return tpl
 603         end
 604 end
 605
 606 redef class MType
 607         fun tpl_signature: Template is abstract
 608 end
 609
 610 redef class MClassType
 611         redef fun tpl_link do return mclass.tpl_link
 612         redef fun tpl_signature do return tpl_link
 613 end
 614
 615 redef class MNullableType
 616         redef fun tpl_signature do
 617                 var tpl = new Template
 618                 tpl.add "nullable "
 619                 tpl.add mtype.tpl_signature
 620                 return tpl
 621         end
 622 end
 623
 624 redef class MGenericType
 625         redef fun tpl_signature do
 626                 var tpl = new Template
 627                 tpl.add tpl_link
 628                 tpl.add "["
 629                 for i in [0..arguments.length[ do
 630                         tpl.add arguments[i].tpl_signature
 631                         if i < arguments.length - 1 then tpl.add ", "
 632                 end
 633                 tpl.add "]"
 634                 return tpl
 635         end
 636 end
 637
 638 redef class MParameterType
 639         redef fun tpl_link do
 640                 var name = mclass.intro.parameter_names[rank]
 641                 return new TplLink.with_title("{mclass.nitdoc_url}#FT_{name}", name, "formal type")
 642         end
 643         redef fun tpl_signature do return tpl_link
 644 end
 645
 646 redef class MVirtualType
 647         redef fun tpl_link do return mproperty.intro.tpl_link
 648         redef fun tpl_signature do return tpl_link
 649 end
 650
 651 redef class MSignature
 652         redef fun tpl_signature do
 653                 var tpl = new Template
 654                 if not mparameters.is_empty then
 655                         tpl.add "("
 656                         for i in [0..mparameters.length[ do
 657                                 tpl.add mparameters[i].tpl_signature
 658                                 if i < mparameters.length - 1 then tpl.add ", "
 659                         end
 660                         tpl.add ")"
 661                 end
 662                 if return_mtype != null then
 663                         tpl.add ": "
 664                         tpl.add return_mtype.tpl_signature
 665                 end
 666                 return tpl
 667         end
 668 end
 669
 670 redef class MParameter
 671         fun tpl_signature: Template do
 672                 var tpl = new Template
 673                 tpl.add "{name}: "
 674                 tpl.add mtype.tpl_signature
 675                 if is_vararg then tpl.add "..."
 676                 return tpl
 677         end
 678 end
 679
 680 redef class ConcernsTree
 681
 682         private var seen = new HashSet[MConcern]
 683
 684         redef fun add(p, e) do
 685                 if seen.has(e) then return
 686                 seen.add e
 687                 super(p, e)
 688         end
 689
 690         fun to_tpl: TplList do
 691                 var lst = new TplList.with_classes(["list-unstyled", "list-definition"])
 692                 for r in roots do
 693                         var li = r.tpl_concern_item
 694                         lst.add_li li
 695                         build_list(r, li)
 696                 end
 697                 return lst
 698         end
 699
 700         private fun build_list(e: MConcern, li: TplListItem) do
 701                 if not sub.has_key(e) then return
 702                 var subs = sub[e]
 703                 var lst = new TplList.with_classes(["list-unstyled", "list-definition"])
 704                 for e2 in subs do
 705                         if e2 isa MGroup and e2.is_root then
 706                                 build_list(e2, li)
 707                         else
 708                                 var sli = e2.tpl_concern_item
 709                                 lst.add_li sli
 710                                 build_list(e2, sli)
 711                         end
 712                 end
 713                 li.append lst
 714         end
 715 end