Document the isAllowed method logic in AbstractJsonDiff

[coderabbitai]

Description

The isAllowed method in AbstractJsonDiff.java (lines 105-127) contains a TODO comment indicating that the logic is unclear and needs serious documentation. This method implements path eligibility checks for COPY operations but its purpose and numeric comparison logic are not self-evident.

Context

• This TODO comment was pre-existing in the original JsonDiff.java on the master branch
• PR Add Jackson 3 support #221 moved this code to AbstractJsonDiff.java as part of Jackson 3.x support
• The logic and behavior were preserved during the refactoring

What needs to be documented

• What "allowed" means in the context of COPY operations
• Why numeric token comparison is performed
• What the edge cases are (e.g., same source/destination)
• The relationship between source/destination path depths
• Any assumptions/limitations of this implementation

References

• PR: Add Jackson 3 support #221
• Comment: Add Jackson 3 support #221 (comment)
• Requested by: @sondemar

Location

src/main/java/com/flipkart/zjsonpatch/AbstractJsonDiff.java lines 105-127