XML: correct API signatures

[ianpartridge]

This PR improves the accuracy of the public API signatures in the XML classes, in comparison with Darwin.

https://developer.apple.com/documentation/foundation/archives_and_serialization/xml_processing_and_modeling was used as a reference.

CC: @rothomp3

[alblue]

There are some changes which I'm not sure improve the existing codebase, even if they bring in the same as Darwin. For example:

- uri:
+ uri URI:

Replacing an internal variable with an uppercase variant of the same name causes unnecessary confusion. In any case, it doesn't affect the public API which remains to call with uri:

The other implementation change is options: to options mask: and then called elsewhere with options:mask. I think this reduces visibility of what it is, especially if the external parameter name is called options. It may be that the internal variable name used mask on Darwin but it doesn't add much value to have it in the Swift codebase.

Lastly there are some changes of capitalised types, like .dtd to .DTDKind. Although this might mirror the original import name from Darwin, I think it is less 'swifty' (as if such a widely used term had specific meaning ...).

That said there other changes (like DTDKind -> XMLDTDNode.DTDKind) which may have a more precise definition, but they probably need to be gone through individually to see if the changes have value or avoid ambiguity.

[ianpartridge]

Thanks for your comments @alblue.

Apple do publish the parameter names of functions. For example, in the case of NSXMLElement.init(name:uri:) which you mentioned, this is documented as init(name: String, uri URI: String?) so I believed it formed part of the published API specification and hence for consistency should be the same in this project. The same applies to the mask parameter name you mention - I didn't see any harm in being consistent.

XMLNode.Kind's DTDKind case is documented here so I believe this is perhaps less controversial and should just be corrected? I did check this one on Darwin too. It is less Swifty as you say but that's not really the point - unless the cases are named the same code cannot be shared between Darwin and Linux without using #if os() - unless I'm missing something.

For your final comment (the DTDKind -> XMLDTDNode.DTDKind changes etc.) I believe these increase clarity in the codebase as the properties are documented in this way. Xcode has Option-click but this type of IDE feature is not widespread for Swift on Linux yet.

[phausler]

Looks correct to me

[phausler]

@swift-ci please test and merge