Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add support for extracting ngdocs from AngularJS AST #157

Closed
wants to merge 3 commits into from
Closed

Add support for extracting ngdocs from AngularJS AST #157

wants to merge 3 commits into from

Conversation

remcohaszing
Copy link

In its current state this is not yet ready. Docs and tests are missing for example. This is basically just a code dump.

I still want to implement the following features:

  • Customize handling of object properties. This can be used to:
    • Resolve factories from providers.
    • Resolve special directive properties, such as restrict.
  • Handle functions as services, instead of just objects.

Furthermore I'd like to add the following, though it's not directly related to this feature:

  • Allow to use @description as a default start tag. It just looks silly to start every comment with this tag with all the boilerplate removed.
  • Enable linking to external projects using a standarized JSON file, similar to objects.inv of intersphinx. Adding @requires for members not in the current project, causes a lot of warnings.

Of course a PR will never be complete without some issue references:

@remcohaszing
feat(ngdoc): allow the use of @ngdoc controller and @ngdoc constant
257176b
@remcohaszing
feat(angular): add package to extract Angular docs from AST
890005c 
In its current form this supports:
- Extracting components chained from angular.module().
  - animation → @ngdoc animation
  - component → @ngdoc directive
  - config - skipped
  - constant → @ngdoc constant
  - controller → @ngdoc constant
  - decorator - skipped
  - directive → @ngdoc directive
  - factory → @ngdoc service
  - provider → @ngdoc provider
  - run - skipped
  - service → @ngdoc service
  - value → @ngdoc service

- Extracting members.
  - class-like members (services, controllers...)
  - returned objects (factories, directives...)
  - literal objects (values, components, ...)

- Resolving function references using escope.
- DI detection, mapping to @requires tags.
- Module dependencies, mapping to @requires tags.
- Combining autogenerated tags with JSDoc.
@remcohaszing
fix(angular): use correct requires
c177980
@wingedfox
Copy link
Contributor

Hi,

Do you have any progress on this package? I'm looking for the same feature set and I'll be glad to help you with the implementation.

Questions:

  1. Is there a need to have @requires auto generation for a module? This may mislead readers as long as Installation section of the docs lists all requires as implicit dependencies.
  2. Have you tried the parsing rules from ng-annotate?
  3. Guess, there's no need to explicitly depend on ngdocs package?
  4. Have you tried to extract @name for the services/properties/etc?

Thanks for contribution!

@remcohaszing
Copy link
Author

Hi @wingedfox

I haven't had much time to continue on this package. Also I'm not sure about the future of Angular 1.x / 2, which hasn't been very motivating to continue on this.

If you want, I can enable issues for my fork and add you as a contributor.

Is there a need to have @requires auto generation for a module? This may mislead readers as long as Installation section of the docs lists all requires as implicit dependencies.

I think it is useful to document the dependencies of one module on another. I suppose this could be changed to something like dependencies instead of requires, but I think this is just a detail.

Have you tried the parsing rules from ng-annotate?

I'm not aware of any of their parsing rules. I've based the parsing on my contributions to eslint-plugin-angular.

Guess, there's no need to explicitly depend on ngdocs package?

I don't recall the details, but I think there is, since the AST is converted to ngdocs which are then passed onto processors from the ngdocs provider. I feel like this may actually not be the best approach tough, but the automatic extraction is probably the most important feature to focus on.

Have you tried to extract @name for the services/properties/etc?

Tried and succeeded.

Members are extracted from class-like components (services, providers), object returning components (service, directive) and literal object components (value, constant).

@petebacondarwin
Copy link
Member

@remcohaszing - sorry I seem to have missed this when it arrived.
Being able to document angular apps is an important feature.
Have you taken a look at the angular-docs branch? And in particular the angularjs package for comparison?

@remcohaszing
Copy link
Author

@petebacondarwin the angular-docs branch uses spahql. I'm not a huge fan of this.

Also, will Angular 1.x still be relevant in the forseeable future? This question hasn't been very motivating me to continue on this feature.

@petebacondarwin petebacondarwin mentioned this pull request May 12, 2016
Closed
@sebpelletier
Copy link

Any updates on this one? Would love to be able to document Controllers and Components now that 1.5.x has implemented the .component() architecture !

@petebacondarwin
Copy link
Member

Nothing from me, I'm afraid. I have been too busy with other projects.

@remcohaszing
Copy link
Author

Sorry, I'm too busy with other projects as well. Also, moved on to Angular2.

Feel free to hijack my PR. ;)

@petebacondarwin
Copy link
Member

Closing as there is no one to work on this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
cla: yes
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

None yet
5 participants
@remcohaszing @wingedfox @petebacondarwin @sebpelletier @googlebot