This is more of a best practices question. I hope that it's okay to ask this question here. I am creating an interface that will be used as part of our API. I have a method called getSomeObject() which has a complected logic behind the scenes and returns SomeObject. Behind the scenes I am calling the method which throws IllegalArgumentException, so there is a possibility that my getSomeObject() method may throw this exception. The problem I have is that the user of the API is not familiar with inner workings of the API and wouldn't understand why the exception was thrown. Since the argument is created inside my method and the user doesn't even know that this argument exists. I was trying to document it, but the reason for this exception would confuse the user of the API. So my question is, what is the best way to go about the situation like this? What is the correct way to document this exception?
Throwing an IllegalArgumentException from a method that does not take any arguments is indeed quite confusing.
I suppose you get that exception if something outside of getSomeObject is not properly defined. So you could maybe throw an IllegalStateException, and document it with an explanation in your javadoc:
@throws IllegalStateException If member variable xyz is not initialised.
This can happen if method `init()` has not been
called before `getSomeObject`.