Idea for neat external module names

[markvandenbrink]

First of all, TypeDoc 0.2.3 works great with TypeScript 1.4! Very happy with that :-)

But, I do have a request. We use a lot of external modules. The names of these modules are currently automatically composed using the relative path of the module surrounded by double quotes. This composed name is then displayed in the generated documentation (title + TOC). The name is also used as file name for the page of the module. In this file name the invalid characters are replaced with an underscore. This results in a bit "ugly" file names for external modules. Module x is displayed as "x" in the documentation and the file name for the page shows _x_.html (see screenshot below). I understand this is done to avoid name conflicts with inline modules with the same name. Seems logical.

May I do the following proposal to streamline the module name and file name:

1. Remove the double quote prefix and suffix out of the reflection name in the onBeginResolve function of the class DynamicModulePlugin;
2. Split up the name and file name in 2 separate properties (currently reflection.name is used for both the display name and the file name). Add a specific property for controlling the file name, so there can be a difference in the display name and the file name;
3. Prefix this file name property for external modules with something like module_. The module with name x will end up with the file name module_x.html.
4. Add a new tag for the external module comment block (for example @module [name]) to allow a custom name override instead of the generated name based on the relative path. This allows neat module naming. If the @module tag is omitted the path name is used instead (just how it now works, but without the double quote prefix and suffix of course :-)).

Let me know what you think of this idea. I can help you with the implementation if you want/like. I also have another idea for a future release: Automatic inheritance diagram generation (using SVG). Doxygen has such a feature for C++ documentation. But a rather simple implementation should be possible in TypeDoc. Basically the class inheritance is already plotted in the "Hierarchy" block. So all the necessary data sits there... As you can see we embed manually drawn diagrams in the description markdown and it looks great. Automatic inheritance diagrams would be a very nice addition in my opinion!

[sebastian-lenz]

Hi Mark, nice to hear from you! That's a great and detailed proposal and I'm with you in most of the points.

• The @module comment tag is a great idea. We can simply set the name of the module reflection to this one.
• The file names of external modules are not optimal, you are right. You've also noted that currently we use this simple behaviour to avoid name collisions. The prefix module_ doesn't appear to be pretty solid to me as there could be both an external module foo and a module module_foo. I would suggest to either:
  • Add a new folder (e.g. "external-modules") in the output directory like the ones we already have ("classes", "interfaces", modules", etc.) and put the docs of external modules there without the underscores.
  • Simply remove the underscores from the files documenting external modules and add a real collision check while generating the output file names.
  As the @module tag could introduce additional conflicts (e.g. the user can name two external modules the same) I would prefer the later one.
• There are already two properties stored with each reflection, there is the name which is used for the title and file name and there is originalName which stores the unprocessed name of the declaration and is not used while generating templates. However, I don't see your point here, why shouldn't we use the name of the external module for the file name? If you change the name using the @module tag the resulting file name would not correspond to the reflection.
• The double quotes help to distinguish between external modules and modules, I'm not sure whether it's a good idea to remove them. For example in the documentation of TypeDoc documentation there are both external modules and modules:
  
  
  
  
  
  Maybe we could introduce a command line option to remove the quotes? This way projects dealing solely with external modules could turn this behaviour off.

[sebastian-lenz]

The class diagram would be a great addition! Do you have a particular module in mind?

[markvandenbrink]

Hi Sebastian,

Thanks for your reply! You are right on the conflicts the @module tag could introduce. That's why I think the overrided module name should only be used as display name in the documentation and should not be used for constructing the file name. I think the current behaviour for the path construction is just fine and should remain the same (though remove the quotes, so there are no unnecessary underscores in the file name). Your idea of a separate folder for external modules is much better than a module_ prefix.

Maybe you can keep the double quotes for the module names if the @module tag is omitted. But I suggest removing them if the module name is overrided. In my opinion the @module tag should just be there to set a different display name. For example we currently have a large project with lots of external modules. They are in a folder structure for example x/y/z.ts. This results in the following display name in the documentation: "x/y/z". We want to be able to optimize these display names. By using the @module tag I could change this to something like X - Y - Z. Or maybe Component X - Subject Y - Module Z.

So, my wish list would be ;-):

• Store external modules in a separate folder;
• Remain the current path name creation based on the source paths, but just remove the unnecessary underscores (which are a result of the double quotes);
• Remain the current behaviour for the display name if the @module tag is omitted. Module z.ts in folder y will result in the display name of "y/z" (with the quotes, just how it now works);
• When the @module tag is used for a module, the display name of that module will be the exact tag value (without double quotes, though this could be a command line setting as you suggest). If this leads to a name collision, this will only lead to duplicate names in the documentation and I think it is the responsibility of the user to avoid this. I just want to be able to use the @module tag to optimize the readability of the module names in the TOC and titles.
• In case of a module name override, change the title (and TOC listing) from External module "x/y/z" to My custom module name. Maybe add a sub title with External module: "x/y/z";
• Maybe split up the TOC in two groups External modules and Modules just like the index page?
• Maybe you can add an icon in the TOC / title bar as extra identification for normal and external modules?

Regarding the class diagrams I dont't have any modules in mind right now. Using inline SVG it shouldn't be quite hard to draw some class rectangles. A simple version just would draw a rectangle per class among each other. But I will think about it and experiment when I have time!

[FlippieCoetser]

Hi Folks,

Re Class Diagrams,

A few months back @stefangrönke and myself developed a transpiler that takes the JSON output of typedoc and generates a XML UML output. Then using GenMyModel we import the UML Model to produce Class Diagrams.

I would recommend to not build a diagramming feature into typedoc but rather collaborate with GenMyModel. They can also provide the diagram in SVG format.

Hope this helps a bit...

[meirgottlieb]

RE: Class Diagrams - I created this plugin to allow generation of UML diagram images from PlantUML syntax in the comments. It doesn't generate the diagrams automatically, but it's easier then creating the images in a separate tool. This syntax supports other types of UML diagrams, such as sequence diagrams, in addition to class diagrams.

Anyways, the supporting library node-plantuml could be used to create automatic diagrams.

[markvandenbrink]

Very nice! I like.

[meirgottlieb]

@markvandenbrink, I noticed you are using SVG, so I added a TypeDoc option for the plugin, umlFormat, that accepts a value of svg or png. Default is png.

[0815fox]

Last weekend I forked @meirgottlieb s typedoc-plantuml module and added automatical generation of uml class diagrams:

https://github.com/0815fox/typedoc-plantuml

[taoqf]

I came to a problem with the double quote, modules/*.html file generated will have a _ prefix, and I will get a 404 when I put these files on my website on github. It seems github will hide these files. Is there a way I could generate files without _?

[rbuckton]

Related to @taoqf's comment, above: https://help.github.com/articles/files-that-start-with-an-underscore-are-missing/

I had to customize my documentation build to add a .nojekyll file to the documentation output directory to get around this.

[krisztianb]

If you are interested in generating UML class diagrams with typedoc you might want to check out this: #175 (comment)