Skip to main content

Generate documentation for Angular projects with Compodoc

Von
Sometimes the structure of Angular projects can become confusing.
After adding tons of components and modules it might be difficult to keep track of what is what.

 Compodoc can help you out by generating a much better to read documentation for your project. It can give you a visual and easy to browse overview of all the code in your application and lots of useful features.

 How to install:
Compodoc is available by npm. First install it globally:
npm install -g @compodoc/compodoc

 Then install it in your project:
npm install --save-dev @compodoc/compodoc

 In a next step you have to add a command to your package.json. In the 'scripts' area add the following line:

"compodoc": "./node_modules/.bin/compodoc -p src/tsconfig.app.json"

 Hint: in the original documentation at the moment it refers to tsconfig.json which is wrong and would give you an error message.

 Finally generate the documentation and open it in the browser:

 npm run compodoc

 compodoc -s

 Open a browser and navigate to http://localhost:8080 to see the documentation.

The documentation shows a navigation that can lead you to all relevant information. The navigation depends on your project and just shows what you have. If you have enumerations, interfaces, classes, services etc. it automatically adds some more sections to the navigation.

 In the 'Getting started' section you can see the content of your README.md file. It can also include a license file. More interesting is the 'Overview' which shows the structure of your application visualized as a chart and counts modules and components.

 In the section 'Modules' all your modules are listed and can be clicked. From the modules you can navigate directly to the components in the module.
Through the section 'Components' you can also directly navigate to the components. 
The component view shows your comments from the sourcecode, the metadata of your component decorator, you can browse the source code, the template and - a really nice feature - you can see a chart of the DOM-Tree.
Another nice functionality in the view of a component, class etc. is that it tells you the line of code where i.e. a method is defined.
When you click the link 'Defined in ... ' you directly navigate to the code and the line is highlighted.

 But there are more charts. If your application uses routing it can display the routes in a nice chart. Here is a screenshot from the Compodoc example documentation:
The routes are clickable so that you can navigate directly to the component or module.

How good is my documenation?
Sure it cannot measure that but it can tell you how much code is covered by proper documentation. In the section 'Documentation coverage' you can see where you are missing documentation.
Here is an example of how it should/could be.😇
There are much more features to explore. To see a nice working example just open the example documentation made by Compodoc.
For more detailed information visit the Compodoc website. 



Labels:

Comments

Post a Comment

Popular posts from this blog

Nested Component - Passing Data to a Child Component

Von
If you want to pass data to a nested component you have to use the @Import decorator. You can find this decorator at @angular/core import  {  Input  }  from   '@angular/core' ; Now I show you how you can use this decorator. In my example I want to pass a counter from a Shopping List to a Shopping Basket Component In the end, the shopping basket should look like this: The Shopping Basket shows the number of items in an array (Shopping List). Everytime we put an item in the basket we count the items in the array this . counter  =  this . selectedProducts . length Now we have to pass the counter to the ShoppingBasketComponent by using property binding < app-shopping-basket  [ count ]= "counter" ></ app-shopping-basket > After this we can use the input decorator at the child component export   class   ShoppingBasketComponent   implements   OnInit  { @ Input ()  count ...
Post a Comment
Read more

Nested Component - Passing Data to a Parent Component

Von
In my previous article  Nested Component - Passing Data to a Child Component , I explained how to pass data from a parent component to a child component.  In this article I will describe how you do the other way, passing data from a child to a parent component. As you know, there is a decorator called @Input for passing data to the child, and of course there is another decorator to passing the data to the parent. This decorator is called @Output. Very obvious. So we have to import this decorator to your parent component import  {  Output  }  from   '@angular/core' ; Now we can use this decorator. The property type of the decorator must be an event. The data to pass becomes the event payload. So we have to import the EventEmitter, too, because in Angular an event is defined with an EventEmitter object. import  {  Output ,  EventEmitter  }  from   '@angular/core' ; Next step is to create a new instance of th...
Post a Comment
Read more

Angular 2: Multiple instances in the same Application

Von
Requirement:  Use multiple Root-Components in the same Application  This Root-Components use the same Implementations and Services Display the Root-Components on the same Single-Page Solution: App-Module preparation: import { BrowserModule, DOCUMENT } from '@angular/platform-browser'; import { NgModule, Inject, Component } from '@angular/core'; export class AppModule { private browser_document; ngDoBootstrap(appRef){ if(this.browser_document.getElementsByTagName('app-root1').length > 0){appRef.bootstrap(AppComponent1);} if(this.browser_document.getElementsByTagName('app-root2').length > 0){appRef.bootstrap(AppComponent2);} } constructor(@Inject(DOCUMENT) private document: any){ this.browser_document = document; } } Service preparation: Angular 2 has two options to provide a service. 1. Single instance For a multiple implementation of more Root-Components we need the second opt...
Post a Comment
Read more