Wie javadoc für Methode schreiben, um eine Karte mit bekannten Schlüsseln

Question

Rückkehr Lets sagen, ich habe eine Methode wie:

Map<String,Object> getData() 

Was ein guter Weg ist, welche Tasten zu dokumentieren und Werte, die sie enthalten, Liste der möglichen Schlüssel unter der Annahme und Arten von Objekten für diese Schlüssel sind bekannt?

[Bearbeiten]

Angenommen, ich kann nicht/nicht das Verfahren in einer Art und Weise ändern, die anderen Code zu ändern erfordern würde, wie kann ich noch vernünftig zu dokumentieren?

Answer 1

Ich empfehle, eine Enumeration zu verwenden, die diese Schlüssel auflistet (und wahrscheinlich eine andere für Wertklassen, wenn das in Ihrem Fall Sinn macht). Angenommen, Sie wissen wirklich, alle möglichen Schlüssel vorne, das wäre am sinnvollsten. Von dort aus: Wenn Ihre Schlüssel wirklich bekannt und begrenzt sind, warum verwenden Sie dann eine Zeichenfolge als Schlüssel? Sie könnten auch Map<EnumForKeys, Object> stattdessen tun.

Das nette Ding ist, dass Sie nettes javadoc auf jede der Enumkonstanten setzen können; siehe here. Und Sie wissen, vorausgesetzt, dass die Wertklasse für jeden anderen Schlüssel festgelegt ist, können Sie eine Methode für diese Enum verwenden, die Ihnen die Wertklasse direkt mitteilt.

Die nächste, aber weit weniger attraktive Option wäre, irgendwo eine statische Liste zu haben, die alle möglichen Schlüssel enthält.

Edit: angesichts Ihrer letzten Kommentar Optionen sind natürlich ziemlich begrenzt. In diesem Fall könnten Sie immer noch eine Enum verwenden, um die möglichen Schlüssel aufzulisten, und eine {@link} in das Javadoc Ihrer Methode einfügen. Sicher, all das ist nur "informell"; aber gut, besser als nichts.