Make inner mechanism of outlet API more obvious in documentation

[benoittgt]

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:

• Outlets array expects kebab-cased names instead of camel-cased ones (like targets do) #615
• Outlet can't have custom name #641
• Feature request: polymorphic outlets #628

[gato-omega]

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 :)

[marcoroth]

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!

[sedubois]

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

[benoittgt]

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

[marcoroth]

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

[dhh]

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.