Clearer headlines with syntax examples #2925
Conversation
Change headline “Actions” to “Use directive” + add a number of additional syntax examples, to make it easier to find the relevant section without ⌘F
| @@ -392,7 +392,7 @@ As with DOM events, if the `on:` directive is used without a value, the componen | |||
| <SomeComponent on:whatever/> | |||
| ``` | |||
|
|
|||
| ### Element bindings | |||
| ### Element bindings (bind:property) | |||
There was a problem hiding this comment.
Would it make more sense to refer to this as bind:attribute?
| @@ -1047,7 +1049,7 @@ A custom animation function can also return a `tick` function, which is called * | |||
|
|
|||
|
|
|||
|
|
|||
| ### Slots | |||
| ### <slot> | |||
There was a problem hiding this comment.
Or Slots (<slot>), but it felt a little redundant...
|
What I'm concerned about with this is it breaking all links to these sections out in the wild. We would be able to update links to these sections from the tutorial and from the Sapper docs (if there are any to any of these sections? not sure), but we wouldn't be able to do anything about any of the other links floating out there in chat or in other people's articles about Svelte or anywhere else. |
|
@Conduitry That's a really good point. I've certainly been frustrated by the same thing when following hash links to various readme's and docs before. It sounds like something that's bound to happen sooner or later, though. Is there some established practice to "redirect" anchor links? Or would it make sense to use anchors that aren't auto-generated from the text itself, so text and anchor ID can be changed independently? |
|
Stable anchors are definitely preferable, though I don't think they should stand in the way of significant improvements. I think some method of redirection is probably our best bet. My larger concern here is that this is fugly:
Maybe the headlines should more directly reflect the syntax?
Come to think of it, I wonder if we should separate out element directives from component directives:
Needs a little bit more work, but you get the idea. Thoughts? |
|
Yes, even better IMO, after all it’s supposed to be an API reference. The concepts are handled much better by tutorials and examples. |
+1! |
I found it hard to use parts of the docs because their headlines did not remind me of the syntax they describe. Especially “Actions”, which is called
usein code. While I was at it I added short syntax examples to a number of other headlines as well. Hopefully this makes it easier to get an overview of the syntax and to lookup documentation for code you may not be 100% sure what it does, without relying on ⌘F.Fair warning: I did this PR from my phone, so autocorrect might have snuck in a typo somewhere.