Java - Comment Inheritance

By -

Comment Inheritance

Class and Interface Inheritance

Comment inheritance occurs in all possible cases of inheritance from classes and interfaces:


  • When a method in a class overrides a method in a superclass
  • When a method in an interface overrides a method in a superinterface
  • When a method in a class implements a method in an interface

In the first two cases, the standard doclet generates the subheading "Overrides" in the documentation for the overriding method. A link to the method being overridden is included, whether or not the comment is inherited.

In the third case, when a method in a specified class implements a method in an interface, the standard doclet generates the subheading "Specified" by in the documentation for the overriding method. A link to the method being implemented is included, whether or not the comment is inherited.

Method Comment Inheritance

The standard doclet allows method comment inheritance in classes and interfaces to fill in missing text or to explicitly inherit method comments. Constructors, fields, and nested classes do not inherit documentation comments.

Note: The source file for an inherited method must be on the path specified by the -sourcepath option for the documentation comment to be available to copy. Neither the class nor its package needs to be passed in on the command line.

Fill in Missing Text

When a main description, or @return, @param, or @throws tag is missing from a method comment, the information is copied from the method it overrides or implements (if any).

When an @param tag for a particular parameter is missing, the comment for that parameter is copied from the method further up the inheritance hierarchy. When an @throws tag for a particular exception is missing, the @throws tag is copied only when that exception is declared.

Explicit Inheritance

Insert the {@inheritDoc} inline tag in a method main description or @return, @param, or @throws tag comment. The corresponding inherited main description or tag comment is copied into that spot.

Method Comments Algorithm

If a method does not have a documentation comment, or has an {@inheritDoc} tag, then the standard doclet uses the following algorithm to search for an applicable comment. The algorithm is designed to find the most specific applicable documentation comment, and to give preference to interfaces over superclasses:

Look in each directly implemented (or extended) interface in the order they appear following the word implements (or extends) in the method declaration. Use the first documentation comment found for this method.
If Step 1 failed to find a documentation comment, then recursively apply this entire algorithm to each directly implemented (or extended) interface in the same order they were examined in Step 1.
When Step 2 fails to find a documentation comment and this is a class other than the Object class, but not an interface:
If the superclass has a documentation comment for this method, then use it.
If Step 3a failed to find a documentation comment, then recursively apply this entire algorithm to the superclass.

Comments

Post a Comment

Popular posts from this blog

Today Walkin 14th-Sept

By -
Image
14th Sept 2017 ( GO Through all List) Read Walkin details properly , Try to call company before attending if possible !!! ==================================== 1. Myntra through fresherworld (Call Based , Venue shared to shortlisted candidates) _____________________________ 2. Magna : Hiring for Client Harman : C++
Read more

Hibernate Search - Elasticsearch with JSON manipulation

By -
Elasticsearch with JSON manipulation Elasticsearch ships with many features. It is possible that at some point, one feature you need will not be exposed by the Search DSL. To work around such limitations, Hibernate Search provides ways to: Transform the HTTP request sent to Elasticsearch for search queries. Read the raw JSON of the HTTP response received from Elasticsearch for search queries. Direct changes to the HTTP request may conflict with Hibernate Search features and be supported differently by different versions of Elasticsearch. Similarly, the content of the HTTP response may change depending on the version of Elasticsearch, depending on which Hibernate Search features are used, and even depending on how Hibernate Search features are implemented. Thus, features relying on direct access to HTTP requests or responses cannot be guaranteed to continue to work when upgrading Hibernate Search, even for micro upgrades (x.y.z to x.y.(z+1)). Use this at your own risk.
Read more

Spring Elasticsearch Operations

By -
Elasticsearch Operations Spring Data Elasticsearch uses two interfaces to define the operations that can be called against an Elasticsearch index. These are ElasticsearchOperations and ReactiveElasticsearchOperations. Whereas the first is used with the classic synchronous implementations, the second one uses reactive infrastructure. The default implementations of the interfaces offer: Read/Write mapping support for domain types. A rich query and criteria api. Resource management and Exception translation. ElasticsearchTemplate The ElasticsearchTemplate is an implementation of the ElasticsearchOperations interface using the Transport Client. @Configuration public class TransportClientConfig extends ElasticsearchConfigurationSupport {   @Bean   public Client elasticsearchClient() throws UnknownHostException {                      Settings settings = Settings.builder().put("cluster.name", "elasticsearch").build();     TransportClient client = new P
Read more