Add @Documented to all annotations in org.python.expose.#415
Conversation
|
I checked the changes very carefully and could not spot any typos... |
|
Yes to |
| * that object. See {@link PyInteger#int_new} for an example of this type of ExposedNew. | ||
| *<p> | ||
| * {@code PyNewWrapper new_, boolean init, PyType subtype, PyObject[] args, String[] keywords}. | ||
| * In this case, the method has full responsibility for creating and initiating the object and |
There was a problem hiding this comment.
| * In this case, the method has full responsibility for creating and initiating the object and | |
| * In this case, the method has full responsibility for creating and initialising the object and |
There was a problem hiding this comment.
Except of course now we run into US vs UK English. (I won't object to either.)
There was a problem hiding this comment.
I suppose, AE is more in line with PSF standard, so "initializing" it will be. Also, my dict says it's somewhat acceptable in BE unlike the other way round.
| * that object. See {@link PyInteger#int_new} for an example of this type of ExposedNew. | ||
| *<p> | ||
| * {@code PyNewWrapper new_, boolean init, PyType subtype, PyObject[] args, String[] keywords}. | ||
| * In this case, the method has full responsibility for creating and initiating the object and |
There was a problem hiding this comment.
Except of course now we run into US vs UK English. (I won't object to either.)
| * @return the base type of this type. Must be another class annotated with {@code ExposedType}. | ||
| * If unspecified, the base is set to {@code object}, or {@code PyObject.class}. |
There was a problem hiding this comment.
If the @return has to be qualified I would probably give the full version in the Javadoc body, and a minimal one in the @return.
There was a problem hiding this comment.
Yes, that's the typical way. My intention was to keep changes minimal and to bring everything into consistent form. Since some class used plainly @return ... without prior main-body doc, while other classes used Returns ... I decided to use the @return way consistently. If no body html is present, but only @return ... block, APIdia employs @return ... content also as main body prefixed with Returns: and as @return ... block tag. So this leads to a proper doc. I used to think Javadoc would do it similarly. However, in conventional Javadoc, this became possible just with Java 16 which introduced the inline {@return ...} tag:
So, if we would build with e.g. Java 17 or later, The solution would be using inline {@return ...}.
| * @return the base type of this type. Must be another class annotated with {@code ExposedType}. | ||
| * If unspecified, the base is set to {@code object}, or {@code PyObject.class}. |
There was a problem hiding this comment.
| * @return the base type of this type. Must be another class annotated with {@code ExposedType}. | |
| * If unspecified, the base is set to {@code object}, or {@code PyObject.class}. | |
| * Return the base type of this type. This must be another class annotated with {@code ExposedType}. | |
| * If not specified (or {@code Object.class} is given), the base is set to Python {@code object}, that is {@code PyObject.class}. | |
| * @return the base type of this type. |
There was a problem hiding this comment.
Yes, this makes sense for the long description of base(). However the principle does not fit naturally to the other methods which have very short doc.
Stewori
changed the title
|
|
||
| /** | ||
| * Returns the __doc__ String for this type. | ||
| * @return the {@code __doc__} string for this type. |
There was a problem hiding this comment.
@jeff5 You see, here I changed it just for consistency. The previous method isBaseType() uses plainly @return in the first place. If we cannot use {@return ...}, maybe it would be best to make them all consistently Returns .... Then, at least it's always readable in the summary, also in older Javadoc.
…be the only content. Change initiate to initialize.
|
Okay, to move on and - I think doc-related concerns have been addressed, I'll merge this one now. |
3 participants
Closes #388