Deprecate asList in favor of asInstanceOf

[scordio]

Triggered by #3105 (comment).

[manusa]

Hi, there are no JavaDocs pointing to the proposed alternative. I had to scavenge the source code to reach to this PR.

Might be interesting to provide the suggested approach.
Which I'm still not sure if is to use:

asInstanceOf(InstanceOfAssertFactories.LIST)

instead

[scordio]

Hi @manusa, which Javadoc were you looking at exactly?

Assert::asList Javadoc has the information you're looking for:

but I just realized AbstractAssert::asList doesn't have it:

[manusa]

🤦 sorry.

Yes, I was meaning the method in the AbstractAssert class.

[scordio]

Thanks for the confirmation. There seems to be a gap in the Javadoc generation, I'm not sure what could be done in AssertJ but I'll have a look.

[manusa]

No worries. I'm not sure if {@inheritDoc} would work in this case and help avoid doc duplication, maybe worth giving a try (seeing now that this PR contained the {@inheritDoc}, not sure what's wrong with me today..).

If not, I'm happy to send a patch with the missing section in AbstractAssert class ;)

[manusa]

OK, I think the problem is (TIL) that inheritDoc needs to be used in the tags too.

https://docs.oracle.com/javase/6/docs/technotes/tools/solaris/javadoc.html#@inheritDoc

Inherits (copies) documentation from the "nearest" inheritable class or implementable interface into the current doc comment at this tag's location. This allows you to write more general comments higher up the inheritance tree, and to write around the copied text.

This tag is valid only in these places in a doc comment:

• In the main description block of a method. In this case, the main description is copied from a class or interface up the hierarchy.
• In the text arguments of the @return, @param and @throws tags of a method. In this case, the tag text is copied from the corresponding tag up the hierarchy.

So I believe something like this is required:

  /**
   * {@inheritDoc}
   * @return {@inheritDoc}
   * @deprecated the deprecation method that can't be inherited
   */

[scordio]

Thanks, I remembered something like that but couldn't find the official reference quickly 🙂

It doesn't mention anything about the @deprecated tag, though. Would you like to give it a try and submit a patch, in case it works?

[manusa]

It doesn't mention anything about the @deprecated tag, though. Would you like to give it a try and submit a patch, in case it works?

I'll submit a patch to add the deprecation suggestion manually.

I've done some checks in my projects and the behavior differs depending on the engine used to generate Javadocs.

For example, in IntelliJ, if the @return {@inheritDoc} is not provided, then the tag is not shown in the editor-rendered Javadoc. However, it is actually shown in the Quick doc viewer (Ctrl+q).
On the other hand, the @return tag is propagated in the javadoc jar too.

In any case, and a common denominator for all is that the @deprecated tag is never propagated, and from what I've seen, it doesn't support the inheritDoc either.