Documentation is confusing

[buko]

First off, great work. Love generics-resolver.

It's worth mentioning that the documentation is confusing. Every time we expose a new programmer to the project it takes a while for them to grok it. Part of the problem is that the README and javadoc are full of words like 'root' and 'base' and it's not clear what these mean. Also root and base are kind of... synonyms. This leads to bugs and unexpected behavior.

Personally, I think it makes sense to refer to a Generic Interface Class and a Generic Implementation Class. (Of course generic interface class doesn't have to be an interface, it can just be a generic base class, but most of the time we're using interfaces etc.) We should make it clear that the type passed to GenericsResolver.resolve is a Generic Implementation Class and the type passed to GenericsContext.type is a Generic Interface Class.

[xvik]

First off, great work. Love generics-resolver.

Thank you!

It's worth mentioning that the documentation is confusing. Every time we expose a new programmer to the project it takes a while for them to grok it.

Yes, I know. It is the curse of open source projects: good documentation requires a lot of time. I will try to improve it before releasing 3.1.0 (but not sure exactly when, not too soon).

This leads to bugs and unexpected behavior.

If possible, could you please share some examples? Maybe exact cases would better point to the most problematic areas. I face usage problems myself from time to time.

Personally, I think it makes sense to refer to a Generic Interface Class and a Generic Implementation Class

I can't say I like these terms: it is confusing too. But I understand your point. It seems to me that some introduction chapter is required in the main docs defining all these terms. Maybe a few diagrams could help. Need to think.

If everyone else reading this, please share the examples of usage problems too,