Skip to content

Add @Documented to all annotations in org.python.expose. #415

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Stewori merged 8 commits into from
May 26, 2026
Merged

Add @Documented to all annotations in org.python.expose. #415

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
2cca372
Update README.md
Stewori Sep 15, 2024
e4dc7af
Merge branch 'jython:master' into master
Stewori Oct 16, 2024
b352dc6
Merge branch 'jython:master' into master
Stewori Mar 2, 2026
d6f713f
Added @Documented to all annotations in org.python.expose.
Stewori Mar 4, 2026
b424d93
Merge branch 'jython:master' into master
Stewori May 20, 2026
3eb2969
Merge branch 'exposed_annotations_documented' into master
Stewori May 21, 2026
444d229
Merge pull request #1 from Stewori/master
Stewori May 21, 2026
38da62c
Improve Javadoc: consistently use Returns if the returns block would …
Stewori May 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions NEWS
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,12 +29,14 @@ New Features
deprecated for removal in Java 26. See https://github.com/jnr/jffi/issues/165

Jython 2.7.5a1 Bugs fixed
- [ GH-388 ] @ExposedType annotation should be @Documented
- [ GH-404 ] Windows code page 65001 (UTF-8) not supported by Jython
- [ GH-384 ] Console encoding inferred incorrectly on Java 21
- [ GH-382 ] Java EE Servlet Namespace Has Been Changed From javax.servlet to jakarta.servlet
- [ GH-356 ] _ast.astlist.__add__ leads to Java exception
- [ GH-84 ] PyServlet Will Need To Use The jakarta.servlet Namespace #84


==============================================================================
Jython 2.7.4
==============================================================================
Expand Down
5 changes: 3 additions & 2 deletions src/org/python/expose/ExposedClassMethod.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,12 @@
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.lang.annotation.Documented;

/**
* Indicates a method should be exposed as a classmethod to Python code.
*
*/
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ExposedClassMethod {
Expand All @@ -24,7 +25,7 @@
String[] defaults() default {};

/**
* Returns the __doc__ String for this method.
* @return the {@code __doc__} string for this method.
*/
String doc() default "";
}
2 changes: 2 additions & 0 deletions src/org/python/expose/ExposedDelete.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,9 @@
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.lang.annotation.Documented;

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target( {ElementType.METHOD})
public @interface ExposedDelete {
Expand Down
4 changes: 3 additions & 1 deletion src/org/python/expose/ExposedGet.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,17 @@
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.lang.annotation.Documented;

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target( {ElementType.METHOD, ElementType.FIELD})
public @interface ExposedGet {

String name() default "";

/**
* Returns the __doc__ String for this descriptor.
* @return the {@code __doc__} string for this descriptor.
*/
String doc() default "";
}
13 changes: 7 additions & 6 deletions src/org/python/expose/ExposedMethod.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,32 +4,33 @@
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.lang.annotation.Documented;

/**
* Indicates a method should be exposed to Python code.
*
*/
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ExposedMethod {

/**
* Returns the names to expose this method as. Defaults to the name of the method.
* @return the names to expose this method as. Defaults to the name of the method.
*/
String[] names() default {};

/**
* Returns default arguments. Starts at the number of arguments - defaults.length.
* @return default arguments. Starts at the number of arguments - defaults.length.
*/
String[] defaults() default {};

/**
* Returns how to expose this method. See {@link MethodType} for the options.
* @return how to expose this method. See {@link MethodType} for the options.
*/
MethodType type() default MethodType.DEFAULT;

/**
* Returns the __doc__ String for this method.
* @return the {@code __doc__} string for this method.
*/
String doc() default "";
}
}
29 changes: 14 additions & 15 deletions src/org/python/expose/ExposedNew.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,27 +4,26 @@
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import org.python.core.PyInteger;
import java.lang.annotation.Documented;

/**
* Can appear on two forms of methods to indicate a method should be part of the {@code __new__}
* object creation. Can only appear once per exposed type.
* <p>
* Can appear on two forms of methods to indicate a method should be part of the __new__ object
* creation. Can only appear once per exposed type.
*<p>
* In the first form, the method must be static and take the arguments
* <code>PyNewWrapper new_, boolean init, PyType
subtype, PyObject[] args, String[] keywords</code>. In this case, the method has full
* responsibility for creating and initting the object and will be invoked for every subtype of this
* exposed type. Essentially it's for object instantiation that must be called for every instance of
* 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

@jeff5 jeff5 Apr 17, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* 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

@jeff5 jeff5 Apr 17, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Except of course now we run into US vs UK English. (I won't object to either.)

@Stewori Stewori May 21, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

* will be invoked for every subtype of this exposed type. Essentially it's for object
* instantiation that must be called for every instance of that object.
* See {@link org.python.core.PyInteger#int_new} for an example of this type of {@code ExposedNew}.
* <p>
* In the second form, the method must be an instance method that takes the standard Jython call
* arguments, <code>PyObject[] args, String[] keywords</code>. In this case, the basic new
* functionality is handled by PyOverridableNew and the method with ExposedNew is called as __init__
* as part of that process. This allows subtypes to completely redefine new and create objects
* however they like.
* arguments, {@code PyObject[] args, String[] keywords}. In this case, the basic new
* functionality is handled by {@link org.python.core.PyOverridableNew} and the method with
* {@code ExposedNew} is called as {@code __init__} as part of that process.
* This allows subtypes to completely redefine new and create objects however they like.
*/
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ExposedNew {}
2 changes: 2 additions & 0 deletions src/org/python/expose/ExposedSet.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,9 @@
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.lang.annotation.Documented;

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target( {ElementType.METHOD, ElementType.FIELD})
public @interface ExposedSet {
Expand Down
10 changes: 6 additions & 4 deletions src/org/python/expose/ExposedType.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.lang.annotation.Documented;

import org.python.core.PyNewWrapper;
import org.python.core.PyObject;
Expand All @@ -12,6 +13,7 @@
/**
* Indicates a given class should be made visible to Python code as a builtin type.
*/
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface ExposedType {
Expand All @@ -22,18 +24,18 @@
String name() default "";

/**
* @return the base type of this type. Must be another class anotated with ExposedType. If
* unspecified, the base is set to object, or PyObject.class.
* @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}.

@jeff5 jeff5 Apr 17, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@Stewori Stewori May 21, 2026 •
edited
Loading

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

https://bugs.openjdk.org/browse/JDK-8075778?page=com.atlassian.jira.plugin.system.issuetabpanels%3Aall-tabpanel

So, if we would build with e.g. Java 17 or later, The solution would be using inline {@return ...}.

@jeff5 jeff5 Apr 17, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* @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.

@Stewori Stewori May 21, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

*/
Class base() default Object.class;

/**
* @return Whether this type allows subclassing.
* @return whether this type allows subclassing.
*/
boolean isBaseType() default true;

/**
* Returns the __doc__ String for this type.
* @return the {@code __doc__} string for this type.

@Stewori Stewori May 21, 2026 •
edited
Loading

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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.

*/
String doc() default "";
}