Skip to content

Conversation

jonpryor
Copy link
Contributor

@jonpryor jonpryor commented 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 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).

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

  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.

@jonpryor jonpryor requested a review from jpobst January 6, 2021 23:10
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.
@jonpryor jonpryor force-pushed the jonp-generator-javadoc-fixes branch from 18c5c2c to e015502 Compare January 6, 2021 23:16
@jonpryor jonpryor merged commit 3894cd7 into dotnet:master Jan 7, 2021
@jpobst jpobst added this to the 11.2 (16.10 / 8.10) milestone Feb 2, 2021
@github-actions github-actions bot locked and limited conversation to collaborators Apr 12, 2024
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants