RFR: 8315767: InetAddress: constructing objects from BSD literal addresses [v4]

[Sergey Chernyshev]

On Thu, 11 Apr 2024 09:21:36 GMT, Daniel Fuchs <dfuchs at openjdk.org> wrote:

>> I updated the docs to link to the class specification, also added an anchor in the spec.
>
> I would rather move the description of the loose syntax fully here, since the only method that accepts it is `Inet4Address.ofPosixLiteral`. We need to be absolutely clear that this is the only method that accepts it. Also, I feel that a link to an external document is not sufficient in this case. It's good to have it, but since we actually implement the parsing in java we should describe clearly the accepted syntax and how we parse it here. We have no control over external documents, they can move, their content can change, etc... I believe that the anchor `Inet4Address##format-posix` should lead to this method here, not to the class-level documentation. Having a short paragraph in the class level documentation that explains that an alternative loose syntax is accepted by a specific method is fine. However I don't feel that describing this loose syntax in the class level API documentation is a good idea.

Moved the algorithm description from the class spec to method spec.

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/18493#discussion_r1560980601