Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Browse files
Browse the repository at this point in the history
Context: dotnet/android#5485 In an attempt to generate updated documentation for API-30 I noticed a minor issue in generator Javadoc import (7574f16): when a `<javadoc/>` element contains multiple `@return` values: <class name="Example" …> <method name="getP" …> <javadoc> <![CDATA[ … @return some docs @return additional docs ]]> </javadoc> </method> </class> We would generate multiple `<returns/>` elements, one for each `@return`: partial class Example { /// <returns>some docs</returns> /// <returns>additional docs</returns> public int P { [Register("getP", …)] get => … } } This is "fine", as far as the C# compiler is concerned, which results in a Documentation XML file containing both `<returns/>`: <doc> <members> <member name="P:Example.P"> <returns>some docs</returns> <returns>additional docs</returns> </member> </members> </doc> The problem is when we later try to *import* this documentation via `mdoc update --import`, as dotnet/android#5485 does; if it's a *method* which contains multiple `<returns/>` elements and mdoc 5.7.4.9 is used (included with macOS Mono 6.12): $ mdoc update -o docs assembly.dll --import assembly.xml Then the resulting imported [**mdoc**(5)][0] documentation only contains the *first* element: <Docs> <summary>To be added.</summary> <returns>some docs</returns> <remarks>To be added.</remarks> </Docs> Using [mdoc 5.8.0][1] will preserve both `<returns/>` elements, but "higher level" tooling such as HTML rendering or IntelliSense may not properly support multiple `<returns/>` elements. *However*, if it's a *property* which contains multiple `<returns/>` elements, then `mdoc update` will convert each `<returns/>` element into a `<value/>` element: $ mdoc update -o docs assembly.dll --import assembly.xml … <Docs> <summary>To be added.</summary> <value>some docs</value> <value>additional docs</value> <remarks>To be added.</remarks> </Docs> This is "odd", but it gets worse: on subsequent `mdoc update` invocations, *additional* `<value/>` elements are created! $ mdoc update -o docs assembly.dll --import assembly.xml … <Docs> <summary>To be added.</summary> <value>additional docs</value> <value>some docs</value> <value>additional docs</value> <remarks>To be added.</remarks> </Docs> $ mdoc update -o docs assembly.dll --import assembly.xml … <Docs> <summary>To be added.</summary> <value>some docs</value> <value>additional docs</value> <value>some docs</value> <value>additional docs</value> <remarks>To be added.</remarks> </Docs> While an `mdoc` bug, we can prevent this from happening by updating the Javadoc importer so that multiple `@returns` blocks are *merged* into a single `<returns/>` element: partial class Example { /// <returns>some docs additional docs</returns> public int P {…} } [0]: http://docs.go-mono.com/?link=man%3amdoc(5) [1]: https://www.nuget.org/packages/mdoc/5.8.0
- Loading branch information