search

ngUpgraders / ng-forward

The default solution for those that want to write Angular 2.x style code in Angular 1.x
411 stars 36 forks source link

jsdocs / generated documentation #34

Closed reppners closed 8 years ago

reppners commented 8 years ago

I recognized that the README is already quite lengthy and there are tons of features hidden in the codebase that are not yet documented. How about opening a wiki for this project to get the docs a little bit more structured? I also would like to contribute to the docs once I figured out myself how to use the ui-router state decorators that I found in the codebase :)

Because when I discovered this project I was all amazed on being able to get rid of angular modules in my code as well as the ability to use the new angular template binding syntax. Really cool stuff :) So I already have MikeRyan52's decorators implemented and then started wondering: No more modules.. how am I going to configure my ui-router states? Taking a quick look at the codebase I saw that there is decorator for this. Yay! So to make this easier for future users I would be glad to help out adding docs and improving docs, but I think stuffing it all into the README will not be feasible in the long run.

@MikeRyan52 Could you add a notice to your angular-decorators project that makes people know about ng-forward? Because I didn't know this successor project until watching the angular-connect talk where it is mentioned.

MikeRyanDev commented 8 years ago

Truthfully, we haven't had much discussion yet on how we plan on structuring our docs. I'm alright with opening up the wiki for this. Thoughts @timkindberg ?

As for @StateComponent, be careful! I think we plan on replacing that with something a little closer to the Angular 2's router:

@Component({ selector: 'my-app' })
@StateConfig([
  { path: '/', component: Home, as: 'home' },
  { path: '/contact', component: Contact, as: 'contact' }
])
class MyApp{ }

Regarding angular-decorators, the plan was to officially deprecate the library once ng-forward matured a bit. For now I'll put a small notice in the README.

reppners commented 8 years ago

Sounds good :+1:

So I think it is safe to take your @StateComponent as a template for rolling a custom solution until the ng-forward routing decorator is ready.

timkindberg commented 8 years ago

Yeah we need more comprehensive docs. I almost would prefer doing it inline in the code with jsdocs since it will move there eventually anyway. But we will still need a getting started and other specialty sections which would be good in a wiki. I'm fine with starting everything in a wiki for now too since it will be easier. It just tends to get out of date.

MikeRyanDev commented 8 years ago

If the TypeScript conversion is successful, we'll be able to use TypeDoc

reppners commented 8 years ago

:+1: for having the docs inline. It is certainly the best way to keep in sync with the code and since this project targets an API that has not yet settled it is even more important it can be done easily.

timkindberg commented 8 years ago

Ok so we'll hold off on more docs until #31 is finished.

timkindberg commented 8 years ago

@reppners or anyone, any chance you'd want to help with some jsdoc documentation in the code?

timkindberg commented 8 years ago

This looks awesome: http://documentation.js.org/, just requires good jsdocs. So I'd say the safest place to start is jsdoc comments, we'll figure out how to generate docs after that.

reppners commented 8 years ago

@timkindberg Sure. There might just be some gaps where I am uncertain of how things work and I'll mark them with an TODO documentation. Another thing that is particularly interesting and relates to documentation: How do we set up examples and where do they live? I like the way the angular2 docs can be switched between languages and the same thing could be applied to this project.

@MikeRyan52 I recognized that you defined some type information inline instead of creating interfaces for them. See ComponentDecorator. Is there a special reason you did so? Is there already workflow for creating the project's d.ts-file where those interfaces would end up?

timkindberg commented 8 years ago

I believe @MikeRyan52 and I decided a manually written documentation was good for now. I've started an API reference here: https://github.com/ngUpgraders/ng-forward/blob/master/API.md

timkindberg commented 8 years ago

Ok I've spent the rest of the night mostly finishing this... just have to fill in the testing bits.

timkindberg commented 8 years ago

Gonna mark this as done and make the testing documentation a milestone 3 goal