Lets say i have a method like:
Map<String,Object> getData()
What's a good way to document what keys and values it will contain, assuming list of possible keys and types of objects for those keys are known?
[edit]
Assume I can't/won't change the method in a way that'd require changing other code, how can i still sensibly document it?
I suggest to use an enum that lists those keys (and probably another one for value classes if that makes sense in your case). Assuming that you really know all potential keys up front, that would make the most sense. Going from there: if your keys are really known, and limited, then why are using a string as key? You could as well do Map<EnumForKeys, Object> instead.
The nice thing is that you can put nice javadoc on each of the enum constants; see here. And you know, assuming that the value class is fixed for each different key, you could put a method on that Enum that actually tells you the value class directly.
The next, but far less appealing option would be to have some static List somewhere, that contains all the potential keys.
Edit: given your last comment options are of course pretty limited. In that case, you could still use an Enum to list the potential keys, and put a {@link} into the javadoc of your method. Sure, all of that is "informal" only; but well, better than nothing.
