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