Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Fix Javadoc parsing issues introduced with API 33 #1071

Closed
pjcollins opened this issue Jan 10, 2023 · 1 comment · Fixed by #1125
Closed

Fix Javadoc parsing issues introduced with API 33 #1071

pjcollins opened this issue Jan 10, 2023 · 1 comment · Fixed by #1125
Assignees
@pjcollins
Labels
bug Component does not function as intended javadoc Issues with consuming Java documentation formats

Comments

@pjcollins
Copy link
Member

There was a recent effort to resolve errors and exceptions that would occur when parsing javadoc for Mono.Android.dll, however this work was done against the API 31 version of Mono.Android.dll. There are a handful of new errors/exceptions introduced when generating docs against API 33 that should be fixed. We should also try to update the API docs generation pipeline to produce a warning or error when these issues are seen in the build log.
@pjcollins pjcollins added bug Component does not function as intended javadoc Issues with consuming Java documentation formats labels Jan 10, 2023
@pjcollins pjcollins self-assigned this Jan 10, 2023
@pjcollins
Copy link
Member Author

The latest logs from https://devdiv.visualstudio.com/DevDiv/_build/results?buildId=7031751&view=results show 28 instances of JavadocImport-Error that we should attempt to resolve.

pjcollins added a commit to dotnet/android that referenced this issue Feb 9, 2023
@pjcollins
[ci] Report issues in the API docs build log
2a8fc0d 
Context: dotnet/java-interop#1071

Adds a step to the API docs build that will fail the job if any
problematic JavadocInfo messages are found in the log.
pjcollins added a commit to dotnet/android that referenced this issue Feb 9, 2023
@pjcollins
[ci] Report issues in the API docs build log
66e0a74 
Context: dotnet/java-interop#1071

Adds a step to the API docs build that will fail the job if any
problematic JavadocInfo messages are found in the log.
pjcollins added a commit to dotnet/android that referenced this issue Feb 9, 2023
@pjcollins
[ci] Report issues in the API docs build log
51719f6 
Context: dotnet/java-interop#1071

Adds a step to the API docs build that will fail the job if any
problematic JavadocInfo messages are found in the log.
@pjcollins pjcollins mentioned this issue Feb 10, 2023
Merged
pjcollins added a commit to dotnet/android that referenced this issue Feb 13, 2023
@pjcollins
[ci] Report issues in the API docs build log (#7784)
7c42c60 
Context: dotnet/java-interop#1071

Adds a step to the API docs build that will fail the job if any
problematic JavadocInfo messages are found in the log.
@pjcollins pjcollins mentioned this issue May 8, 2023
Merged
pjcollins added a commit that referenced this issue Jun 13, 2023
@pjcollins
[Java.Interop.Tools.JavaSource] Fix up common HTML tags
d442c15 
Fixes: #1071

The latest API docs update contained a couple dozen parsing issues due
to broken `<code></code>` elements, reserved inline characters in
`<code>` elements, and other issues.  These issues have been fixed by
no longer attempting to parse `<code>` elements with Irony.  Instead, an
HTML processing step has been added which replaces, removes, or decodes
well known HTML tags after the javadoc is parsed.

Parsing for `<a/>` elements has also been updated to fix all 83 cases
where `href` attribute parsing would fail.  Now when we we encounter an
`<a/>` element that points to code or a local path we will only include
the element value in the javadoc, and not the full `href` attribute.

Readability of our generated docs should be improved by both of these
changes, as there will be fewer encoded character entities in places
where they are not necessary.
@pjcollins pjcollins mentioned this issue Jun 13, 2023
Merged
jonpryor pushed a commit that referenced this issue Jul 12, 2023
@pjcollins
[Java.Interop.Tools.JavaSource] Improve <code> parsing (#1125)
151b03e 
Fixes: #1071

The latest API docs update contained a couple dozen parsing issues
due to `<code/>` parsing, including:

  * Closing element doesn't match opening element: `<code>null</null>`
  * Content including `@`: `<code>android:label="@string/resolve_title"</code>`
  * Closing element is actually an opening element:
    `<code>Activity.RESULT_OK<code>`
  * Improper element nesting: `<code><pre><p>content</code></pre></p>`
  * Use of attributes: `<code class=prettyprint>content<code>`

Fix this by replacing `CodeElementDeclaration` to use a new
`CodeElementContentTerm` terminal, which is a "greedy regex" which
grabs `<code` until one of:

  * `</code>`
  * `</null>`
  * `<code>`

The result of `CodeElementDeclaration` is the end of the `<code>`
element until the beginning of one of the above terminators:

  * `<code>null</null>` becomes `<c>null</c>`
  * `<code>android:label="@string/resolve_title"</code>` becomes
    `<c>android:label="@string/resolve_title"</c>`.`
  * `<code>Activity.RESULT_OK<code>` becomes `<c>Activity.RESULT_OK</c>`.
  * `<code><pre><p>content</code></pre></p>` becomes the mess
    `<c>&lt;pre&gt;&lt;p&gt;some content</c>&lt;/pre&gt;&lt;/p&gt;` 🤷‍♂️
  * `<code class=prettyprint>content<code>` becomes `<c>content</c>`.`
jonpryor pushed a commit to dotnet/android that referenced this issue Jul 14, 2023
@dependabot @jpobst
Bump to xamarin/Java.Interop/main@151b03e (#8188)
c984e8b 
Fixes: dotnet/java-interop#1071

Context: dotnet/java-interop@d0231c5

Changes: dotnet/java-interop@e1121ea...151b03e

  * dotnet/java-interop@151b03ee: [Java.Interop.Tools.JavaSource] Improve `<code>` parsing  (dotnet/java-interop#1125)
  * dotnet/java-interop@6a9f5cbb: [Java.Interop.Tools.JavaSource] Improve `<a>` parsing (dotnet/java-interop#1126)
  * dotnet/java-interop@d0231c5c: [generator] Override methods should match base deprecated info (dotnet/java-interop#1130)

Commit dotnet/java-interop@d0231c5c updated `override` methods'
"obsolete" data to match its base method.  This results in several
`[ObsoleteOSPlatform]` attributes being switched to `[Obsolete]`
attributes.  Updated `acceptable-breakages` to allow this.

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Jonathan Pobst <jonathan.pobst@microsoft.com>
@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.
Assignees

@pjcollins pjcollins

Labels
bug Component does not function as intended javadoc Issues with consuming Java documentation formats
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

[Java.Interop.Tools.JavaSource] Improve <code> parsing dotnet/java-interop
1 participant
@pjcollins