Skip to content
This repository has been archived by the owner on Jan 23, 2022. It is now read-only.

Home

Jump to bottom
m7r edited this page Dec 6, 2013 · 9 revisions

Warning

This article is out of date

Check out the Writing AngularJS documentation wiki article to see what's possible.

Angular documentation

Angular documentation takes an pretty unique approach for its documentation. Not only does it product it automatically -- this is trivial these days -- but it compiles the documentation into an application, which enables nice animations and more importantly, search. Moreover, it divides the documentation into two parts:

  • API documentation
  • Tutorials

The API documentation is presented in Angular's lingo, meaning, in the building blocks that Angular uses to define its system:

  • directives
  • filters
  • services

The automatic documentation generation does NOT produce documentation out of internal comments, for classes and methods. For that, one can browse the source files.

Project documentation

The same approach that works great for the AngularJS project, makes a lot of sense for any project, especially if it derives from Angular. Naturally, such projects have their building blocks defined as well in Angular's lingo, and therefore continuing the documentation in the same fashion makes a lot of sense. It directs the developers to build their tasks as a encapsulated and abstracted components, hiding internal detailed and promoting reusability, a blessed approach anywhere. It also guides the developers to create tutorial style documentation, a very helpful resource for newcomers and peers.

##Documentation how-to

  1. File could have one or more block comments. Each block commented generates an entry in the documentation app

  2. a block comment should include at least the following three keywords:

    a. @ngdoc

    b. @name

    c. @description

  3. @ngdoc: after this keyword, you should put one of angular 'doc'

  • overview
  • directive
  • filter
  • interface
  • service
  • object
  • function

  1. The @name has its own syntax which tells ngdocs how to associate the unit. The syntax follows the following

      `<module name>.<unit>:<unit name>`

'Unit' is any one of the building blocks that are defined for this project. Obviously, some of them are Angular units, such as directives and filters. For example, it could read ogApp.directive:productdetails

In this case, we will see:

  • productdetails appear under directive area in the left navigation bar of the documentation application
  • Once clicked, the title will present productdetails (directive in module ogApp)
  1. The rules are pretty custom and spotted with special cases, but here they are:
  • When only <module name> is present, it will create a new module area
  • Only service, directive and filter will create a new sub-module area in the left nav bar
  • For a service, you need to make sure that no <unit> is present. For example ogApp.$productdetailsDataProvider
  • For a type, you need to make sure that no <unit> is present and the name starts uppercase. For example ogApp.Product
  • <unit> could actually be anything you'd like. But it doesnt fall under service, directive or filter, it will go under the module area.

  1. The @description is the place to write the full description.

  2. The @methodOf keyword allows to document methods of units. You'll need to use @methodOf <module name>.<unit>:<unit name>#<method name>.

This will add a to the unit page a subtitle for the , with the parameters and description as described

  1. The @param keyword allows to document parameters. It needs to be followed by a type inside curly brackets and then a description: @param {$http} $http injected service for the data

  2. If you need to show HTML examples, you need to use the @example keyword. This should be followed by <example > and <file > directives and will give an Example section on the page!

    @example

    <example module="ogApp" > 

     `<file name="jdx.html" >`

     HTML example come here ==> `<div class="lior" ></div >`

 `</file >`

    </example >

  3. For all units, a Usage subsection will be added with automatically generated code example to show how to call the unit.

  4. Angular itself has more ngdoc-types which are not yet supported with ngdocs

  • global API
  • property
Clone this wiki locally