Skip to content

feat: added support + automated documentation extraction for summary metadata#1974

Merged
cka-y merged 9 commits intomasterfrom
feat/doc
Feb 26, 2025
Merged

feat: added support + automated documentation extraction for summary metadata#1974
cka-y merged 9 commits intomasterfrom
feat/doc

Conversation

@cka-y
Copy link
Contributor

@cka-y cka-y commented Feb 7, 2025

Summary

This PR improves documentation. A preview of the updated summary metadata can be found here.

Key Changes:

  • Annotation Processors:
    Added the summary annotation processor

  • Documentation Enhancements:
    Updated the Javadoc for all summary metadata elements.

Expected Behavior:

The documentation is automatically generated from Javadoc comments by the annotation processor, which produces a summary-metadata.json file in the web client’s static folder. This file is then used to update the documentation displayed on rules.html. When adding new fields ensure each element is properly documented. Corresponding tests verify that these standards are maintained.
Screenshot 2025-02-10 at 12 36 56 PM

Please make sure these boxes are checked before submitting your pull request - thanks!

  • Run the unit tests with gradle test to make sure you didn't break anything
  • Add or update any needed documentation to the repo
  • Format the title like "feat: [new feature short description]". Title must follow the Conventional Commit Specification(https://www.conventionalcommits.org/en/v1.0.0/).
  • Linked all relevant issues
  • Include screenshot(s) showing how this pull request works and fixes the issue(s)

@cka-y cka-y changed the title feat: added support + automated documentation extraction for summary … feat: added support + automated documentation extraction for summary metadata Feb 7, 2025
@cka-y cka-y marked this pull request as draft February 7, 2025 17:43
@cka-y cka-y marked this pull request as ready for review February 10, 2025 17:07
@github-actions
Copy link
Contributor

📝 Acceptance Test Report

📋 Summary

✅ The rule acceptance has passed for commit 900b97b
Download the full acceptance test report here (report will disappear after 90 days).

📊 Notices Comparison

New Errors (0 out of 1809 datasets, ~0%) ✅

No changes were detected due to the code change.

Dropped Errors (0 out of 1809 datasets, ~0%) ✅

No changes were detected due to the code change.

New Warnings (0 out of 1809 datasets, ~0%) ✅

No changes were detected due to the code change.

Dropped Warnings (0 out of 1809 datasets, ~0%) ✅

No changes were detected due to the code change.

🛡️ Corruption Check

0 out of 1809 sources (~0 %) are corrupted.

⏱️ Performance Assessment

📈 Validation Time

Assess the performance in terms of seconds taken for the validation process.

Time Metric Dataset ID Reference (s) Latest (s) Difference (s)
Average -- 3.70 3.92 ⬆️+0.21
Median -- 1.39 1.52 ⬆️+0.13
Standard Deviation -- 10.62 10.78 ⬆️+0.16
Minimum in References Reports us-california-flex-v2-developer-test-feed-2-gtfs-1818 0.46 0.57 ⬆️+0.11
Maximum in Reference Reports gb-unknown-uk-aggregate-feed-gtfs-2014 292.68 301.75 ⬆️+9.07
Minimum in Latest Reports us-california-camarillo-area-transit-gtfs-2234 0.51 0.54 ⬆️+0.04
Maximum in Latest Reports gb-unknown-uk-aggregate-feed-gtfs-2014 292.68 301.75 ⬆️+9.07
📜 Memory Consumption
Metric Dataset ID Reference (s) Latest (s) Difference (s)
Average -- 470.73 MiB 469.55 MiB ⬇️-1.18 MiB
Median -- 333.92 MiB 335.92 MiB ⬆️+2.00 MiB
Standard Deviation -- 794.90 MiB 776.54 MiB ⬇️-18.36 MiB
Minimum in References Reports ro-vrancea-consiliul-judetean-vrancea-gtfs-1984 38.25 MiB 69.34 MiB ⬆️+31.08 MiB
Maximum in Reference Reports gb-unknown-uk-aggregate-feed-gtfs-2014 10.80 GiB 10.81 GiB ⬆️+12.70 MiB
Minimum in Latest Reports us-california-redding-area-bus-authority-raba-gtfs-114 46.04 MiB 38.88 MiB ⬇️-7.16 MiB
Maximum in Latest Reports gb-unknown-uk-aggregate-feed-gtfs-2014 10.80 GiB 10.81 GiB ⬆️+12.70 MiB

@cka-y cka-y linked an issue Feb 10, 2025 that may be closed by this pull request
@MobilityData MobilityData deleted a comment from github-actions bot Feb 10, 2025
*/
public final String countryCode;

/** Date of the validation. */
Copy link
Contributor

@jcpitre jcpitre Feb 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is the date used for compiling notices related to dates. It can be different from the date the validation was run.
Normally this date should be the same as the date the validator was run for someone using the web validator.
But for the cli version a different date can be specified.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

cc @emmambd for the description. What should it be changed to?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jcpitre I'm confused how notice compiling time and validation time differ - can you share an example of what this would look like in the CLI?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Merging this PR for now to be able to complete #1964. We can always open a new issue to change the description of this field if necessary 🙂

Copy link
Contributor

@qcdyx qcdyx left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great work, LGTM!

cli/build.gradle Outdated
implementation project(':main')
implementation 'com.beust:jcommander:1.48'
implementation 'com.google.code.gson:gson:2.8.6'
implementation 'com.google.code.gson:gson:2.9.1'
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just a heads-up: This will cause merge conflicts in dependencies since the PR that resolves dependency versions has already been merged, and it uses libs.gson.

@cka-y cka-y merged commit 7146461 into master Feb 26, 2025
134 checks passed
@cka-y cka-y deleted the feat/doc branch February 26, 2025 17:24
@github-actions
Copy link
Contributor

📝 Acceptance Test Report

📋 Summary

✅ The rule acceptance has passed for commit 07a1bab
Download the full acceptance test report here (report will disappear after 90 days).

📊 Notices Comparison

New Errors (0 out of 1821 datasets, ~0%) ✅

No changes were detected due to the code change.

Dropped Errors (0 out of 1821 datasets, ~0%) ✅

No changes were detected due to the code change.

New Warnings (0 out of 1821 datasets, ~0%) ✅

No changes were detected due to the code change.

Dropped Warnings (0 out of 1821 datasets, ~0%) ✅

No changes were detected due to the code change.

🛡️ Corruption Check

0 out of 1821 sources (~0 %) are corrupted.

⏱️ Performance Assessment

📈 Validation Time

Assess the performance in terms of seconds taken for the validation process.

Time Metric Dataset ID Reference (s) Latest (s) Difference (s)
Average -- 3.73 3.80 ⬆️+0.07
Median -- 1.34 1.39 ⬆️+0.05
Standard Deviation -- 11.04 11.02 ⬇️-0.02
Minimum in References Reports us-oregon-hut-airport-shuttle-gtfs-635 0.47 0.51 ⬆️+0.04
Maximum in Reference Reports gb-unknown-uk-aggregate-feed-gtfs-2014 294.42 290.46 ⬇️-3.96
Minimum in Latest Reports ph-unknown-hm-transport-inc-and-robinsons-malls-gtfs-1105 0.49 0.49 ⬇️-0.00
Maximum in Latest Reports gb-unknown-uk-aggregate-feed-gtfs-2014 294.42 290.46 ⬇️-3.96
📜 Memory Consumption
Metric Dataset ID Reference (s) Latest (s) Difference (s)
Average -- 461.04 MiB 471.64 MiB ⬆️+10.60 MiB
Median -- 335.92 MiB 335.92 MiB ⬇️0 bytes
Standard Deviation -- 746.67 MiB 767.32 MiB ⬆️+20.65 MiB
Minimum in References Reports ro-vrancea-consiliul-judetean-vrancea-gtfs-1984 38.08 MiB 69.00 MiB ⬆️+30.92 MiB
Maximum in Reference Reports gb-unknown-uk-aggregate-feed-gtfs-2014 10.95 GiB 10.93 GiB ⬇️-22.93 MiB
Minimum in Latest Reports us-colorado-boulder-county-gtfs-2191 395.92 MiB 38.79 MiB ⬇️-357.13 MiB
Maximum in Latest Reports gb-unknown-uk-aggregate-feed-gtfs-2014 10.95 GiB 10.93 GiB ⬇️-22.93 MiB

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document extracted feed metadata

4 participants