elixir-lang
Search suggestions in sidebar should mention if they are deprecated
I use the sidebar for a quick search to remind me what is the module a functions belongs to. For instance if I type "cwd", I got System.cwd as a suggestion, but I doesn't mention that is is deprecated. So I guess it should be added.
I would rather not include deprecated entries in the autocomplete. Thoughts?
Use italics? Other than that I don't see any other option.
Additionally the search results and the tooltips do not show that the function is deprectated either.
Which tooltips?
When you hover a function. For instance in the Search result page, I hightlight were it could be included that the functions is deprecated.
If we add it to the sidebar where you suggest, I think it could be interpreted as if the whole module is deprecated, not just that particular search hit. If we add it on the same line, e.g.: cwd/0 (_deprecated_), then I believe we'd eventually run into a problem with long function names, there won't be enough space to display both the function and the deprecation label.
It would be in the same place where we show (type) for some matches that are types. We could use italics if space is a problem. By using it users will learn that when the italic is shown, it means it is deprecated
Gotcha.
I missed Jose's previous comment, I agree with him: I think we could simply not suggest deprecated functions in the first place.
But in the hovering tooltips, we can show that the function is deprecated. It will save users' precious time.
I’d suggest that we still show deprecated results, because if someone is looking for docs for a deprecated function, it could be confusing if it doesn’t show up in the search.
I would add a deprecation notice in the main “search results” section, but I don’t think we’d need to put that in the sidebar.
Maybe replace
System.cwd/0 (function)
with
System.cwd/0 (function) (deprecated)
?
Just a suggestion, I think hiding docs for deprecated functions could be annoying to people looking for information about them.
Nowadays, what would be the correct behavior here @josevalim @wojtekmach? Hiding deprecated functions from the sidebar search?
The only case I think this would not be ideal is if an user consuming some "old" book or guide tries to check docs on some function that is shown but it is already deprecated.
Yeah, I think hiding could be confusing/bad, so a small mention can be helpful. :)