Skip to content

Add some signposting to the String docs for pattern matching #13514

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

Merged
merged 2 commits into from
Apr 28, 2024

Conversation

DeemoONeill
Copy link
Contributor

As a user of the docs, when looking for information on how to pattern match with strings and binaries the first place one looks is the String docs.

Currently there isn't anything here for pattern matching besides a small example matching a character. The user would either have to go from the reference section to the patterns and guards guide or go to the <<>>/1 special forms docs.

This change just adds a link to the special forms docs and the guide to signpost the user to those resources.

As a user of the docs, when looking for information on how to pattern
match with strings and binaries the first place one looks is the String
docs.

Currently there isn't anything here for pattern matching besides
a small example matching a character. The user would either have to
go from the reference section to the patterns and guards guide
or go to the <<>>/1 special forms docs.

This change just adds a link to the special forms docs and the guide
to signpost the user to those resources.
@DeemoONeill
Copy link
Contributor Author

For reference my flow when looking for this information was

String module, i just saw the single <<eacute::utf8>> = "é" example. but nothing more.
|> Pattern matching guide. nothing here about binaries
|> Binaries, strings, and charlists guide. There is pattern matching here but nothing signposting the user to where there is more information
|> Scrolled down got to the mix-otp section and figured i would have seen something at this point
|> googled it, Binaries, strings, and charlists guide is the top result. there are some articles but none link back to the docs
|> asked on discord. got linked to the <<>>/1 special form docs.

Then when i was going to make this pull request, doing a search in github i found the patterns and guards reference which is at the very bottom of the guides and this does link to the special forms docs

Comment on lines 204 to 205
See the documentation for [`<<>>`](`<<>>/1`) or the Patterns and Guards
guide for more information on binary pattern matching
Copy link
Member

@whatyouhide whatyouhide Apr 27, 2024

Choose a reason for hiding this comment

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

I think you can link to the guide as well:

Suggested change
See the documentation for [`<<>>`](`<<>>/1`) or the Patterns and Guards
guide for more information on binary pattern matching
See the documentation for [`<<>>`](`<<>>/1`) and the [*Patterns and Guards*
guide](patterns-and-guards.md) for more information on binary pattern matching.

Can you try out make docs_elixir locally with this and see if the link is to the right page?

Copy link
Contributor

Choose a reason for hiding this comment

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

.md perhaps?
Another instance from Kernel doc:

[Patterns and guards](patterns-and-guards.md)

Copy link
Member

Choose a reason for hiding this comment

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

Ah sure yep

Copy link
Contributor Author

Choose a reason for hiding this comment

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

done. built the docs and it links to the correct pages

@DeemoONeill
Copy link
Contributor Author

Thanks for the feedback I'll sort that out when I'm home.

I might change the order too, "see patterns and guards (link) and <<>> for more information on binary pattern matching. "

Go from less specific to more specific.

@josevalim josevalim merged commit b8760a1 into elixir-lang:main Apr 28, 2024
@josevalim
Copy link
Member

💚 💙 💜 💛 ❤️

@DeemoONeill DeemoONeill deleted the signpost_binary_patterns branch April 28, 2024 19:56
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.

4 participants