16

Does anyone have any experience in documenting/structuring angularjs projects so the JSDoc can generate nice comments (for your directives, controllers, filters etc.) in an HTML format? At the moment it generates one file with the _global class that points to the namespace of my app with couple functions and that's it...

Or maybe there is a better way to generate html version of doc blocks in angularjs?

PS: I am using standard jsdoc syntax to document my code (@param, @return etc.)

Update: My specific question is: Is there any way to generate html documentation for angularjs doc blocks to cover all controllers/directives/filters etc.? When ran JSDoc command line utility it covered only about 5% of my code in the HTML report...

Thanks!

alchemication
  • 5,084
  • 6
  • 22
  • 21
  • Is there a specific question? – Ben Lesh Oct 11 '12 at 15:15
  • Would that be ok as a question (pelase see updated content and subject)? I spent a lot of time documenting my program and the html output from JSDoc command line utility is just horrible and does not cover even 5% of my app... – alchemication Oct 11 '12 at 15:33

3 Answers3

33

I have been working on a grunt plugin that utilizes AngularJS's documentation generation code. It follows their syntax and output. grunt-docular. The link shows documentation generation for the docular source as well as the original AngularJS source. It's configurable and extendible.

Go to grunt-docular and find the install link for an example of creating your own documentation

Aaron Butacov
  • 32,415
  • 8
  • 47
  • 61
John David Five
  • 811
  • 11
  • 15
  • This is a better answer now. I'd delete mine if I could, but I can't because it's accepted. – Ben Lesh Feb 04 '14 at 21:48
  • The main website for the project is gone. – Aaron Butacov Jun 13 '14 at 13:54
  • @AaronHarun For what it's worth, my company has stepped in and we're now sponsoring the docular project. The site should be back up within the next few days and there will be a corporate maintainer with a bunch of people eager to contribute. – Stephen Jul 02 '14 at 02:08
  • @Stephen i've been trying to get docular up and running as an alternative to ngdocs but i'm battling to get it working. we're using yaml to configure grunt. could this be cauding the issue? – zpydee Sep 10 '14 at 14:14
  • @zpydee Unsure. Please leave a message with some of the configuration details on the issue list (https://github.com/Vertafore/docular/issues) and I'll take a look today. – Stephen Sep 10 '14 at 19:02
  • What about "dgeni"? https://github.com/angular/angular.js/wiki/Writing-AngularJS-Documentation https://github.com/angular/dgeni – pearpages Jul 24 '15 at 10:18
4

EDIT: See John David Five's answer below

My answer was much, much older and should no longer be accepted.

Community
  • 1
  • 1
Ben Lesh
  • 107,825
  • 47
  • 247
  • 232
  • Thanks, what I was looking for is a properly documented Angular app, not Angular source code, but still learned some tricks from there... – alchemication Oct 12 '12 at 09:31
  • That's a confusing distinction. At lot of their source is in angular modules, which is an angular app. There are examples in there for how to document a directive, a filter, a service, etc. – Ben Lesh Oct 12 '12 at 11:55
  • Did you manage to get a correct output? Because directives and filters are function calls and not function definitions, I'm wondering if it's even possible to document them... – Florian F Nov 14 '12 at 14:23
1

Build steps:

Docs will be availiable at build/docs folder. If you have PHP 5.5 you can view it with:

  • cd build
  • php -S localhost:8000
  • view in browser: http://localhost:8000/docs/index.html
Amadu Bah
  • 2,919
  • 28
  • 27