What are you thoughts about QueryParser being able to know about custom Query implementations? E.g. if I were to write a MyQuery class and implemen the toString method a certain way, how would QueryParser know about MyQuery?
Right - this has always been a limitation. That is why the wording has been loosened a lot of the years in Query.toString(). There is really not a lot you can do here - non of the SpanQuerys produce parsable toStrings because there is no support for SpanQuerys in the QueryParser. I think a couple others do not work either. I think its just got to be something we live with - you simply can't count on it - but if possible, its nice I guess - especially for the core queries.
Is it possible to extend QueryParser?
Its possible to extend it, but not really syntax wise. The new QueryParser in contrib will likely be more extensable in that regard in a way - though still you would be building another parser - it would just hopefully allow for a lot of non cut and paste reuse if you just want to add syntax (I think - I'm only at the surface with the new QP).
Overall though, its not really a contract, because its not something users can adhere to. Its more of an internal nicety suggestion - but if your not a Query already in the QP, your out of luck anyway - at best you could toString to a primitive query parsable String if your custom query rewrites to primitives.