[generator] Add --doc-comment-verbosity=intellisense+extraremarks
#774
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
generator
only emits the copyright notice whengenerator --doc-comment-verbosity=full
is 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 update
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.
Footnotes
mdoc update
for "full" output will eventually fail with:This happens because the generated
<altmember/>
is bad. ↩