i don't personally think it would be confusing, but i also don't think we need to advertise it in the example.
we should definitely encourage using similarity per field type, but for people who have used it in the past, having it continue to work as a "global default" when fieldTypes don't define a similarity gives us nice back-compatibility.
I agree here, this is a good compromise and by not advertising it in the example, I won't have concerns about the example being confusing.
More generally though, i'm thinking that the same <similarity/> tag can be used for both the old style (global default) Similarity/SimilarityFactory and the new SimilarityProviderFactory using instanceof checks...
I have to disagree on this one. The new SimilarityProvider serves a totally different purpose, its not a global sim: it answers to requests for sims for specific fields. The only reason I provided a factory for it, is so that users can tune the parts of lucene's relevance ranking system that are not per-field: coord() and queryNorm(). But its not a way to configure tf() or idf() or anything like that. In the patch I added this with "expert" to the example, though we could remove it from the example entirely if its too expert (might be?)
So I think we should do as you suggest and allow a global <similarity/> that is the default term weighting unless otherwise specified by a field, but we shouldn't confuse this with the parts that arent field-specific...
The one other thing i just noticed is that you have SimilarityProviderFactory.init(SolrParams)
I configured it this way, because this is how <similarity/> worked before (and it was just enough XML to not scare me away). Is it possible we can defer this improvement to a later issue? I think we should give this a little more thought, for example if we do this its a break in the API for <similarityFactory/>, which this patch does not actually do: it only MOVES it to the fieldType.