Symbols Glossary

[zainab-ali]

A first cut of the symbols glossary.
There are still many symbols and links to be added.

[codecov-io]

Current coverage is 88.77%

Merging #1094 into master will not change coverage

@@             master      #1094   diff @@
==========================================
  Files           228        228          
  Lines          3012       3012          
  Methods        2962       2962          
  Messages          0          0          
  Branches         47         47          
==========================================
  Hits           2674       2674          
  Misses          338        338          
  Partials          0          0          

Powered by Codecov. Last updated by 8f94d13...84c5a34

[DavidGregory084]

Maybe the source location for this should be the generated source file in src_managed?

[non]

I also think we could leave out the source location and do pretty well. I'd rather have a column that relates the syntax to the type class, if possible. E.g.

| Symbol  | Name       | Typeclass | Definition | Import |
|---------|------------|----|------------------|----------------|
| x =!= y | not equals | Eq | Eq[A].neqv(x, y) | cats.syntax.eq |

[non]

I also have mixed feelings about the imports. It is nice to let people know where things are, but I worry that this is encouraging people to use the piecemeal imports, which are often a source of frustration.

[zainab-ali]

@non I agree with getting rid of the imports and having an example usage.

I'm undecided about what to do with the source file. People often want to know where a symbol is defined, but because most of them use simulacrum or macro expansions, there isn't a straightforward location. @DavidGregory084 wouldn't references to src_managed confuse people, as it isn't present on GitHub? Perhaps a link to the source file or syntax file would be better.
I'm leaning towards:

|Symbol    | Name       | Typeclass                                             | Definition |
| -------   | --------  | ------------------------------------------------------ | ------------- |
|  x =!= y  |  not equals  | [cats.kernel.Eq](../../../../cats/kernel/Eq.scala)  | Eq[A].neqv(x, y) |

[non]

OK, I'm fine with links to the files. In the case of generated sources, maybe we should italicize the name instead of linkifying it, and then putting a note at the bottom that italicized names are from generated source?

[ceedubs]

Would it make sense to link to the scaladoc instead of the source? That should have the generated methods, and it contains a link to the source in the non-generated case.

[zainab-ali]

Right, I've added all the symbols I could find. Some points to note:

1. The links point to the typeclass file, not the syntax file. I thought this would be more clear alongside the function definitions.
2. Some function definitions differ from the ones in the cats codebase, because the functions in the codebase are on Ops classes. followedBy is an example of this.
3. I changed the definitions to include argument types and a return type
4. Not all of the symbols I expected to see were present in the codebase. The <*> on the Applicative is missing, as are the Arrow symbols

I'm also fairly new to functional programming in general, so I may have made some mistakes with the symbol names.

[ceedubs]

Thanks for putting so much work into this @zainab-ali! I know symbols can often be a barrier for people, so I really like the idea of trying to clear them up.

I think it'd be really neat if we could somehow inject this data into the symbols scaladoc page -- then we could be sure that it never goes out of date. I don't know if that's actually possible though. Are you aware of that page? It looks like there might be a couple of items on there that aren't in here.

[ceedubs]

Should these two links go to the FlatMap type class instead of syntax?

[zainab-ali]

@ceedubs the symbols scaladoc page looks really useful! I hadn't heard of it before - perhaps it needs to be publicized a bit more? It would certainly be good to put this information there, if possible.

EDIT: It seems to be inbaked in scaladoc itself. Thanks for showing me the existence of such a page! I'll research the possibilities of adding to it.

[zainab-ali]

I've hunted around, but I don't think it's possible to inject the data into the scaladoc page. Nevertheless, I've added a link to it.

[non]

This is great! 👍 Thanks!

[ceedubs]

Does anyone have thoughts on #1094 (comment) ?

This has a pretty messy git history (33 commits) for a fairly isolated change. This isn't really the standard procedure, but it might be nice to squash commits here.

[non]

I'd be fine with squashing the commits. Or not. Either way.

[zainab-ali]

Squashing the commits is proving difficult because of the merges in between.
I've created another branch, and am tackling this in PR #1136.