search

angular / components

Component infrastructure and Material Design components for Angular
https://material.angular.io
MIT License
24.34k stars 6.74k forks source link

docs(material): examples in jsdocs #24024

Open wSedlacek opened 2 years ago

wSedlacek commented 2 years ago

Feature Description

Currently the jsdocs on components is very minimal, with very little detail

https://github.com/angular/components/blob/39921f43382e3abc90c14fd8602d0cf371239fce/src/material/button/button.ts#L62-L64

Example how how this displays in VS Code

Screen Shot 2021-11-27 at 20 01 22

With material-experiential things seem greatly improved https://github.com/angular/components/blob/39921f43382e3abc90c14fd8602d0cf371239fce/src/material-experimental/mdc-button/button.ts#L30-L38

But I think there is still a few things missing. There is a link to the material design docs which is great, but it would be awesome to have a link to the Angular Material documentation which has code examples and live demos.

Additionally it would be cool to have code examples in the JSDocs themselves. This helps with discoverability of different ways of using components, for example showing the mat-flat-button as an example would be quite useful on the mat-button JSDoc

Use Case

Having faster access to documentation will not only help new developers who are not familiar with all the APIs that @angular/material has to offer, but also help refresh the memory of any developers who works in many context, such as backend work.

wagnermaciel commented 2 years ago

I think it would make sense to add links to the appropriate doc site, but don't need to include code examples in the JSDocs themselves as those can be found on the site.

This seems like a good issue for an external contributor

wSedlacek commented 2 years ago

but don't need to include code examples in the JSDocs themselves as those can be found on the site.

That's fair

bonganiSibiya commented 2 years ago

Is anyone working in this? I would like to pick it up.

wagnermaciel commented 2 years ago

@bonganiSibiya All yours. Nobody has started this issue yet

angular-robot[bot] commented 2 years ago

Just a heads up that we kicked off a community voting process for your feature request. There are 20 days until the voting process ends.

Find more details about Angular's feature request process in our documentation.

angular-robot[bot] commented 2 years ago

Thank you for submitting your feature request! Looks like during the polling process it didn't collect a sufficient number of votes to move to the next stage.

We want to keep Angular rich and ergonomic and at the same time be mindful about its scope and learning journey. If you think your request could live outside Angular's scope, we'd encourage you to collaborate with the community on publishing it as an open source package.

You can find more details about the feature request process in our documentation.

michaelfaith commented 1 year ago

Since this issue originally referenced what's now Legacy (and used material-experimental, which is now the main implementation as being the good example), is this still an issue that needs addressing?