runem / web-component-analyzer

CLI that analyzes web components and emits documentation
https://runem.github.io/web-component-analyzer
MIT License
499 stars 61 forks source link

Add methods to JSON output #146

Open kevinmpowell opened 4 years ago

kevinmpowell commented 4 years ago

I tried to do this myself, but quickly got out of my depth. I'd like to see support for JSDoc methods in the JSON format. It's already there in the markdown format.

image

runem commented 4 years ago

I agree that it would be valuable, but I will only implement it in the experimental JSON format when we agree on something at https://github.com/webcomponents/custom-elements-json. Please read those discussions and add your thoughts there if necessary :-)

kevinmpowell commented 4 years ago

@runem what does agreement look like? Looks like it's already been discussed:

https://github.com/webcomponents/custom-elements-json/issues/5#issuecomment-546843921

Is there an official doc that I'm not seeing?

runem commented 4 years ago

There exists two PR's with concrete suggestions on how the format could look :-) The problem right now with the experimental JSON format that web-component-analyzer outputs, is that it becomes really difficult to output more complex structures such as custom types, modules, inheritance, methods, eg.

This PR opens up for a JSON structure that allows outputting more complex concepts. I intend to implement that structure as parallel experimental JSON format that will temporarily exist side by side with the existing experimental JSON format. This way we can experiment and play around with concrete outputs of the JSON format in order to better access the optimal output. This output format will include methods.

All in all, I think that there is consensus that methods should be included in the final JSON format. The question is however, how to model it in JSON.

kevinmpowell commented 4 years ago

@runem thanks for the response. I'd love to use that experimental format in the interim. I understand the blocker that is the standardization conversation.