-
Bug
-
Resolution: Fixed
-
P4
-
9
Current format is:
[FullTypeName DOT] Ident LPAREN [FullTypeName ParamName {COMMA FullTypeName ParamName} [COMMA FullTypeName ELLIPSIS ParamName]] RPAREN
There are some problems:
1. No return type
Return type is one of the important things when we think about methods.
2. No type parameters
When the parameter types is the type parameter, the documentation is difficult to understand:
java.util.Optional.of(T arg0) // what is T? what is the bound of T?
3. No thrown type
4. ParamName is useless
Because it is always arg0, arg1, arg2, ..., argN.
5. FullTypeName is too verbose.
The class name is not simplified even if it is already imported.
I propose the following format:
Documentation = Constructor | Method
Constructor = ConstructorName Arguments ThrowsOpt
ConstructorName = [TypeParameters] SimplifiedType
Arguments = LPAREN [SimplifiedType {COMMA SimplifiedType} [COMMA SimplifiedType ELLIPSIS]] RPAREN
ThworsOpt = [THROWS SimplifiedType {COMMA SimplifiedType}]
Method = ReturnType MethodName Arguments ThrowsOpt
ReturnType = SimplifiedType
MethodName = [SimplifiedType DOT] [TypeParameters] Ident
SimplifiedType is simplified by SnippetMaps#fullClassNameAndPackageToClass and with TypeParameter.
Ex:
void printf(String, Object...)
void f(List<String>, Function<? super String,? extends String>)
(when j.u.List, j.u.f.Function are imported)
[FullTypeName DOT] Ident LPAREN [FullTypeName ParamName {COMMA FullTypeName ParamName} [COMMA FullTypeName ELLIPSIS ParamName]] RPAREN
There are some problems:
1. No return type
Return type is one of the important things when we think about methods.
2. No type parameters
When the parameter types is the type parameter, the documentation is difficult to understand:
java.util.Optional.of(T arg0) // what is T? what is the bound of T?
3. No thrown type
4. ParamName is useless
Because it is always arg0, arg1, arg2, ..., argN.
5. FullTypeName is too verbose.
The class name is not simplified even if it is already imported.
I propose the following format:
Documentation = Constructor | Method
Constructor = ConstructorName Arguments ThrowsOpt
ConstructorName = [TypeParameters] SimplifiedType
Arguments = LPAREN [SimplifiedType {COMMA SimplifiedType} [COMMA SimplifiedType ELLIPSIS]] RPAREN
ThworsOpt = [THROWS SimplifiedType {COMMA SimplifiedType}]
Method = ReturnType MethodName Arguments ThrowsOpt
ReturnType = SimplifiedType
MethodName = [SimplifiedType DOT] [TypeParameters] Ident
SimplifiedType is simplified by SnippetMaps#fullClassNameAndPackageToClass and with TypeParameter.
Ex:
void printf(String, Object...)
void f(List<String>, Function<? super String,? extends String>)
(when j.u.List, j.u.f.Function are imported)
- relates to
-
JDK-8145473 JShell: should print actual parameter name as documentation if it could
-
- Closed
-
-
JDK-8131019 jshell tool: access javadoc from tool
-
- Closed
-