What happens if the pattern is already built? Could you document that behavior with an @throws and a mention in the general description?

In general, avoid specifying the type of a parameter or return value in the Javadoc. It's already documented in the method header, and is automatically included in the generated documentation. Duplicating the types from the method header in the Javadoc is redundant, and from experience, it often leads to the types in the Javadoc being forgotten and going out-of-date :)

So, I'd suggest something like this:

Note: Sometimes it is appropriate to add @link tags that relate to the types of parameters and return values if it's the easiest way to describe a concept, but as a general rule, I find that it's better not to duplicate that information.

This isn't quite what this method does. When preserving line numbers, this method adds as many lines as needed for the current line to match the end line of the given element.

Same comment as before, avoid specifying the types of parameters and return values in the Javadoc. Say something about them instead.

This Javadoc does not really say anything, it mostly just duplicates the method header.

What this method does is to wrap a Method in an RtMethod. Note that it's entirely fine to have a Javadoc without a general description. That is to say with only tags, like so:

Could you try to improve this Javadoc to say something meaningful?

Typos :)

Thanks for pointing this out :)

One thing I am curious about is why one of my commits failed 1 out of 7 tests (locally I passed all the test cases), when I committed the same changes again, it passed all 7.

That was a connection timeout, it had nothing to do with your work: https://github.com/INRIA/spoon/runs/2186431693#step:8:3661

We have some problems with an old Maven repository that we used to use, it goes offline from time to time. The last traces of it are being removed (#3860).

Thanks for letting me know the cause.

I think you misinterpreted my feedback about referring to types: just writing e.g. CtElement is less informative than {@link CtElment}, and it still refers explicitly to the type. Look for example at this standard library Javadoc. The Javadoc describes the semantic meaning of the values, not their types. Note also that the type of each parameter is very evident in the Javadoc as they appear in the signature, so unless it actually helps understand something, I would omit the explicit types.

What I meant was something like this:

// no; refers explicitly to the type, which is already specified in the method header
* @param e is a {@link CtElement} whose line number will be preserved by adding newlines

// no; also refers explicitly to the type, but there will be no clickable link in the Javadoc HTML
* @param e is a CtElement whose line number will be preserved by adding newlines

// yes; does not refer explicitly to the type, we just say "element", which is more general
* @param e element whose line number will be preserved by adding newlines

To be clear, if you need to refer to the type, use @link tags. If you don't need to refer to the type, describe the value in natural language without the type name.

Thanks for sharing the example and clearing things up, for now on I will just ask if something isn't clear to me.

for now on I will just ask if something isn't clear to me.

Very good!

The @param is good in terms of information, but the comment about types still applies. If you want to refer to types (which isn't unreasonable here; this method just wraps an object of one type in an object of another type), then use @link.

The @return is much too specific. Only write what's actually important to a caller of the method. Does it matter how the wrapper is created? What if we change RtMethod to a fluent API instead, should that matter to this method? I would suggest something like @return a wrapper around the passed method instead, because that describes the semantics of the value, and not the details of its type or how it came to be.

Thanks for the suggestions, I will incorporate the necessary changes in the next commit.