Project Documentation

[kingcody]

It has come to my attention that there is a strong need for documentation of the generated code. While the code itself in many places is commented, I do understand that it may be difficult for some to follow the code flow and thus the layout of the project.

Over the past few days I've been working with several documentation generators, namely: JSDoc, Dgeni, and Doxx. While I know that JSDoc is a very popular tool, I find it fails to demonstrate the layout of the server side code very well. The main reason being is that it seems to be geared more towards OOP instead of the looser, more modular structure used in this project.

I think that Doxx has some real potential to be used for documenting the sever side code for the project. I've been working with some custom templates and I think it works fairly well already. As far as the client code goes, I've definitely spent less time in that department but, I think Dgeni will work well for that.

Any other thoughts?

[DaftMonk]

I don't have a lot of experience with documentation generators besides JSDoc, so I'll just see what other people have to say. But I would definitely agree that we need to to work on adding documentation.

[kingcody]

@DaftMonk do you have a preference on doc presentation? I'm currently working with a Jade template that gets compiled for each file (see Doxx Example) so you end up with a folder structure of html files that resembles the server folder structure. Doxx uses visionmedia/dox to parse out the doc symbols (aka atoms) into a json structure for each file. I mainly like the flexibility of that setup over JSDoc's.

I'm wondering though, if we were to go with something like Dox(x), where would you like to include the documentation section? Also should we use a generated project as the base of the doc, perhaps incorporated into the demo site? I ask because it would factor into what we use for a docs template. ie: flat html or angular driven.

edit

[andrewstuart]

I'm working on a branch right now using grunt-ngdocs as an option in the initial generator. It's already got all the configuration set up for client side and to livereload the docs and regenerate them on code changes, which works nicely as you have your own documentation alongside your site and both livereloading on changes. I'm working on going through the code and documenting in ngdocs format so that there is some nice filled documentation right off the bat with the generator, and all generated code will be documented with ngdocs.

I just pushed it to the ngdocs branch, so you can check it out there.

After having one tiny issue with grunt-ngdocs and the example/file directives that I'm sure was just me missing something (documentation on all these documentation tools is ironically sparse), I looked into what Angular is currently using, which is dgeni, developed by them.

It looks poised to do really powerful and clean document generation for any type of annotation (through providers, DI, and great configuration) but it's not been super friendly to me thus far. Still a young project from what I can tell.

[kingcody]

@andrewstuart thats awesome, I'm really glad to see others working on this as well! As for ngdocs, I have not heard of that one yet, I'll definitely check out that branch. I've been focusing on the server code documentation more so, but I'd definitely be interested in helping out with your ngdocs/dgeni endeavors. Just let me know if there's anything I can do :)

[kingcody]

Also, you bring up a really good point I might add. I've been working under the assumption that docs generation would be in the (fullstack) generator, but baking it right into the generated project sound like a really neat idea 👍

[andrewstuart]

I thought it was funny to see the issue today. I also just started thinking about docs and working on this a few days ago.

It's something I did on the last project at work, and it was crazy invaluable having my own service, controller, app, etc. documentation formatted very similarly to the angular docs and livereloaded as I went. It made the effort to document my code seem much, much more valuable because of the instant feedback.

I tend to think dgeni is probably the ideal solution for both sides, as it seems the most flexibe and it's clearly already working for the ngdocs specification, which is used by the angular team itself and I think a really clean, powerful syntax.

My only concern with dgeni is the amount of time I spent banging my head against it last night with little effort. My guess is I'll have to dissect how the angular project is configuring it in order to better understand how best to use it.

[kingcody]

@andrewstuart are you suggesting dgeni for server code documentation (as well)?

[andrewstuart]

I'm probably not in a good position to recommend it, since I haven't actually gotten it to work aside from the pre-made dgeni-example repo. However, it does seem like an ideal solution to generate a really nice documentation site with a section for both the client and server code.

I definitely plan on playing with it more to see how easy that would be, and trying to think of generator users as well who may want to modify how it works.

Have you had any success getting dgeni to work?

[kingcody]

I have not tried to be honest. I will however see what I can do as far as scaffolding it up for a project. I'll let you know how it goes ;)

[andrewstuart]

Here's a quick screenshot of what grunt-ngdocs generates.

Custom styles, images, and scripts can all be loaded as well to customize the site more. Example directives are also available that work similarly to the examples on the angular site. Source tabs, and of course the two rendered together as a working demo.

[kingcody]

I checked out the ngdoc branch, it works well I must say. Also, I took a stab at using grunt-dgeni but I wasn't able to have any success. I think I'll look using dgeni directly and see where that gets me. Were you able to generate any form of docs with dgeni?

[andrewstuart]

Unfortunately, not yet. I've been trying to look more into how Angular has it configured so I can figure it out more. Progress might be a bit slower during the week, though. I'm trying to find a worthwhile way to integrate it into my current projects so I have a good excuse to hack on it at work.