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.

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

Use -jsdoc plugins from woocommerce/grow #475

Merged
merged 2 commits into from
Jun 9, 2022
Merged

Conversation

tomalec
Copy link
Member

@tomalec tomalec commented Jun 8, 2022

This PR requires woocommerce/grow#13

Changes proposed in this Pull Request:

Use -jsdoc plugins from woocommerce/grow,
instead of maintaining a local copy.

Screenshots:

Detailed test instructions:

  1. Remove a few lines from https://github.com/woocommerce/pinterest-for-woocommerce/blob/develop/TRACKING.md?plain=1#L17-L22 to see that the result is generated
  2. npm i
    npm run doc:tracking
  3. Check that TRACKING.md is generated correctly

Additional details:

Changelog entry

instead of maintaining a local copy.
Copy link
Contributor

@jorgemd24 jorgemd24 left a comment

Choose a reason for hiding this comment

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

Thanks @tomalec, I followed the steps mentioned in the PR and I can see that the TRACKING.md is generated correctly.

LGTM 👍

@@ -8,9 +8,9 @@ When a store opts in to WooCommerce usage tracking and uses _Pinterest for WooCo

As in WooCommerce core, only non-sensitive data about how a store is set up and managed is tracked. We **do not track or store personal data** from your clients.

<woo-tracking-jsdoc>
<woocommerce-grow-tracking-jsdoc>
Copy link
Contributor

Choose a reason for hiding this comment

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

Not related to Pinterest itself, more related to woocommerce-grow-jsdoc 😄 wouldn't it be better to use a more generic name instead of woocommerce-grow-tracking-jsdoc? Something like <tracking-jsdoc>? I am just thinking that maybe other divisions or external people want to use this package outside of Grow and they would like to have something more generic. It is not an issue of course but more a curiosity.

Copy link
Member Author

Choose a reason for hiding this comment

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

We briefly discussed it at woocommerce/grow#6 (review) and I created a somewhat related issue in woocommerce/grow#7

I think once, we decide it's ready for publishing to the outer world, we could change that. To me one of the purposes of /grow is to incubate tools before proposing to external people.

Before that, I think it would be nice to have that explicit distinction, between which things are already woo-generic, and which are our incubated things.

However, it would require tedious work to change that later on, and having it generic and short from day one could give more benefits.


Speaking of <tracking-jsdoc> the good practice for custom element names is to prefix them with the vendor. Even though technically this is not a custom element per se, just a custom named HTMLElement (HTMLUnknownElement`). But IMHO it's good to stick to that practice, as we may someday create a custom element for that that could do some work in the browser.

Personally, I'd rather shorten this to <woo-tracking-jsdoc>/<wc-tracking-jsdoc>

Copy link
Contributor

Choose a reason for hiding this comment

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

Thanks, @tomalec for your detailed explanation! 😄

@tomalec tomalec merged commit 268c09a into develop Jun 9, 2022
@tomalec tomalec deleted the tweak/externalize-jsdoc branch June 9, 2022 10:59
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.

2 participants