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.

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

Make inner mechanism of outlet API more obvious in documentation #663

Merged
merged 3 commits into from
Jun 15, 2023

Conversation

benoittgt
Copy link
Contributor

@benoittgt benoittgt commented Feb 17, 2023

Hello

This is the first contributions linked to #659

I found it was difficult to understand how outlet API was working at first sight. Especially when you have a specific CSS selector that does not match the controller name.

Also I found it hard to deal with controller name with dash, so I make it more obious in the doc.

I know that the documentation looks less "Stimulus" style, but I think it will help dev to understand the inner mechanism of outlet.

I use jsfiddle as a playground. I was not able to reproduce the errors from the doc @marcoroth.

Related:

@benoittgt benoittgt marked this pull request as ready for review February 17, 2023 17:32
@gato-omega
Copy link

I actually had the same kind of issues understanding the docs since there's many ways the naming could be interpreted and some ambiguity on which specific naming conventions to use in certain situations (mostly the namespaced controllers and if the outlet could have a custom name or not, etc.). A bit of diversity in the examples/docs when the names are not "simple" could to the trick :)

Copy link
Member

@marcoroth marcoroth left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for taking this on @benoittgt!

I also think that it really helps to have distinct examples for each of the APIs, as you mentioned. So this looks good to me!

@marcoroth marcoroth merged commit 69488c7 into hotwired:main Jun 15, 2023
@benoittgt benoittgt deleted the 659-outlet-doc branch June 15, 2023 15:13
AndersGM pushed a commit to AndersGM/stimulus that referenced this pull request Jun 16, 2023
…wired#663)

* Make inner mechanism of outlet API more obvious in documentation

* Reduce chance of highlighting irrelevant variables

---------

Co-authored-by: Marco Roth <[email protected]>
@sedubois
Copy link
Contributor

NB: this change hasn't yet been published to the website:
https://stimulus.hotwired.dev/reference/outlets

@benoittgt
Copy link
Contributor Author

Hello @marcoroth do you think the website could be refreshed? :)

@marcoroth
Copy link
Member

I can't do that, sadly. Maybe @dhh can trigger it?

@dhh
Copy link
Member

dhh commented Sep 4, 2023

Done. Probably should move to the same method we have with Turbo where the docs just live in the website repo. I get how it's nice to tie docs and code together, but this syncing process is pretty inconvenient.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Development

Successfully merging this pull request may close these issues.

5 participants