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 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

How to implement a search field in Angular X that starts some action as soon as you stop typing

Von
Everybody knows the Google search that displays some recommendations while you are typing. Some times when you are developing an application you might need a similar functionality for implementing a kind of free text search to quickly find results in a long list of data stored in a database that might be filtered and delivered by a webservice in the background.  The requirement: The search should happen without clicking a button but it should not start right after each single character you have typed. It should wait a short moment and after you have stopped typing immediately start the search. The implementation is quite simple and the same way you could do that in Javascript. First we need to prepare our template to have an input field in which the user can type in a search string.  Whenever the user types a character a function should be called. This is done with the keyup event. (keyup)="searchChanged($event)" In our component we have to defin...
Post a Comment
Read more