[generator] Add --doc-comment-verbosity=intellisense+extraremarks#774
Merged
jonpryor merged 1 commit intodotnet:masterfrom Jan 7, 2021
Merged
Conversation
jpobst
approved these changes
Jan 6, 2021
Context: dotnet/android@a7413a2 Context: https://github.com/xamarin/android-api-docs Context: https://github.com/xamarin/android-api-docs/blob/035344f961fd391bcad9715ea690afa3b88d6142/docs/Mono.Android/en/Java.Lang/Object.xml#L34-L41 dotnet/android@a7413a23 asked: > What do we want? Updated documentation! About that… Our existing documentation at [xamarin/android-api-docs][0] includes a copyright notice for every member, e.g. <remarks> <para> <format type="text/html"> <a href="https://developer.android.com/reference/java/lang/Object" title="Reference documentation">Android platform documentation</a> </format> </para> <para>Portions of this page are modifications based on work created and shared by the <format type="text/html"><a href="https://developers.google.com/terms/site-policies" title="Android Open Source Project">Android Open Source Project</a></format> and used according to terms described in the <format type="text/html"><a href="https://creativecommons.org/licenses/by/2.5/" title="Creative Commons 2.5 Attribution License">Creative Commons 2.5 Attribution License.</a></format></para> </remarks> The need to provide this copyright notice is why 7574f16 added the `java-source-utils.jar --doc-*` options, so that the above notice could be appropriate inserted. The problem is that `generator` only emits the copyright notice when `generator --doc-comment-verbosity=full` is used, and "full" output is incomplete (many constructs aren't supported) and buggy (many constructs result in "invalid" member references which may cause [breakage with `mdoc update`][1] [^1]). Square this circle by adding a new `generator --doc-comment-verbosity=intellisense+extraremarks` value, which emits "intellisense" *plus* the "extra remarks" output, which includes the copyright notice and documentation links. This allows us to have the benefits of intellisense (faster, semantically correct output) and *also* retain the extras. [0]: https://github.com/xamarin/android-api-docs [1]: https://discord.com/channels/732297728826277939/732297837953679412/796506764438142978 [^1]: `mdoc update` for "full" output will eventually fail with: System.Xml.XPath.XPathException: 'altmember[@cref='!:Java.Interop.Tools.JavaSource.SourceJavadocToXmldocGrammar+<ToXmlContent>d__9 and <c> <see cref="#EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_REASON_CODE" /> </c> In the case where ErrorCode contains a value of 0, it means it's an unknown error. E.g Intent only contains <c> <see cref="#OPERATION_DOWNLOAD" /> </c> and ErrorCode is 0 implies this is an unknown Download error.']' has an invalid token. at MS.Internal.Xml.XPath.XPathParser.CheckToken (MS.Internal.Xml.XPath.XPathScanner+LexKind t) [0x00023] in <6062976fd2cb473f91f94556758db404>:0 … This happens because the generated `<altmember/>` is bad.
18c5c2c to
e015502
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Context: dotnet/android@a7413a2
Context: https://github.com/xamarin/android-api-docs
Context: https://github.com/xamarin/android-api-docs/blob/035344f961fd391bcad9715ea690afa3b88d6142/docs/Mono.Android/en/Java.Lang/Object.xml#L34-L41
dotnet/android@a7413a23 asked:
About that…
Our existing documentation at xamarin/android-api-docs includes
a copyright notice for every member, e.g.
The need to provide this copyright notice is why 7574f16 added the
java-source-utils.jar --doc-*options, so that the above noticecould be appropriate inserted.
The problem is that
generatoronly emits the copyright notice whengenerator --doc-comment-verbosity=fullis used, and "full" outputis incomplete (many constructs aren't supported) and buggy (many
constructs result in "invalid" member references which may cause
breakage with
mdoc update1).Square this circle by adding a new
generator --doc-comment-verbosity=intellisense+extraremarksvalue,which emits "intellisense" plus the "extra remarks" output, which
includes the copyright notice and documentation links.
This allows us to have the benefits of intellisense (faster,
semantically correct output) and also retain the extras.
Footnotes
mdoc updatefor "full" output will eventually fail with:This happens because the generated
<altmember/>is bad. ↩