Add tracking JSDoc template and plugins.

[tomalec]

Changes proposed in this Pull Request:

• Add woo-tracking-jsdoc,
  copied from https://github.com/woocommerce/google-listings-and-ads/tree/c69c514315d5f70a9c6c602c33c678525c0296c1
  • package.json
• Add fires-description to the README
• Update README to mention npm installation and simplify usage.
• Add headers for event properties table.

Screenshots:

Detailed test instructions:

See woocommerce/google-listings-and-ads#1521 for example

1. npm install --save-dev https://gitpkg.now.sh/woocommerce/grow/packages/js/tracking-jsdoc?add/jsdoc
2. Follow the README instruction to configure the package.

Additional details:

Changelog entry

Add JSDoc template and plugins for Tracking docs.

[puntope]

❓

As far as I understand, one of the advantages of having this in the wocommerce-grow repo is avoiding to load the dependencies in the package.json

I deleted in GLA these plugins:

jsdoc
jsdoc-advanced-types-plugin
jsdoc-plugin-intersection
jsdoc-plugin-typescript

Then when I run npm run doc:tracking I got an error since jsdoc is not loaded.

So the question ❓ is:

Have you considered loading a bin in the tool?

Then we can just do:

docs:tracking: woocommerce-grow-tracking-jsdoc ./js/src .jsdocrc.json

[puntope]

❓

In .jsdocrc.json I see jsdoc-plugin-intersection as well as "recurse": true

Not sure if we can remove them. If they are useful we could add it to the Readme as well?

[tomalec]

We cannot remove them, as they are needed. jsdoc-plugin-intersection - is a plugin that lets jsdoc parse types intersections. and recurse is a CLI argument that makes jsdoc parse the code recursively.

I wouldn't mention them in woo-tracking-jsdoc as those configs have nothing to do with tracking, and are not related at all to this plugin.
Potentially, I could add/mention them in a potential new package mentioned in #6 (comment)

[puntope]

Problem of not mentioning anything is that when a developer implements the tool he wont add those into .jsdocrc.json creating errors.

As far as I see, in the README.md should be instructions about how to have the tool running.

[tomalec]

But the tool described here is woo-tracking-jsdoc plugin, not the entire jsdoc.

In Google Listing & Ads README.md, we do not mention how to add AutomateWoo to WooCommerce, or how to add variable product to WC products list.

[tomalec]

This PR does not deliver a "tool to generate all the docs for an extension" (yet, we could implement that in the following PRs). This PR only moves one jsdoc template and a few pluginsfor tracking docs onyl.

[puntope]

This discussion is closely related to #6 (comment)

[puntope]

we could implement that in the following PRs

I can buy that :)

[tomalec]

Yes, I got your point about that. Since in theory are conceptually separated things.

But in the reality what I experienced was that after installing woocommerce-grow-tracking-jsdoc I could not track anything since I needed dependencies and configs that doesn't appear in the Readme (see intersection, recurse and jsdoc-advanced-types-plugin and jsdoc itself).

By adding those to the repo I just run doc:tracking and go the only thing that (maybe) I need to do is to add the provided config in the readme.

In reality, they have also separated things.
If you would have a repo whose source code is already parseable by jsdoc, adding woocommerce-grow-tracking-jsdoc. If you create a repo with a single js file with a simple JSDoc in it, it will work.

BTW jsdoc is added as a peer dependency, so you get a warning if you don't have it. (The amount of warnings we get in GLA, and warning blindness it introduces, are a separate topics, beyond the scope of PR ;) )

[tomalec]

What I think we could add to this readme is

0. Set up jsdoc, so it parses your source code.

From the perspective of this plugin that would be enough to make docs:tracking work once you just added it.

As well, we cannot anticipate all the JS and JSDoc parser problems one may get with their source code.

[puntope]

So my main comment is:

Are we (grow) using JSDOC for anything besides tracking the docs? --> I think no
Are we (grow) planning to use JSDOC for anything besides tracking the docs? --> I think no, neither

But I'm fine if we have 2 different repos. One for tracking only and other for loading jsdoc base deps

[tomalec]

❓
As far as I understand, one of the advantages of having this in the wocommerce-grow repo is avoiding to load the dependencies in the package.json

To me, the main goal of extracting dev tools to this repo is to reduce the noise and bloat in the extension's repo.
That noise could be in a form of custom code, scripts, dependencies, big config files, etc.

This goal is achieved here to a valuable extent, as we removed 4 files, and left only jsdoc config there.

So I think it's a good first step before any other potential changes. Just move the code more-or-less as it was.

I deleted in GLA these plugins_dependencies_:

jsdoc
jsdoc-advanced-types-plugin
jsdoc-plugin-intersection
jsdoc-plugin-typescript

Then when I run npm run doc:tracking I got an error since jsdoc is not loaded.

The custom, but shareable, tracking-specific code was modularized in a form of "conventional" jsdoc plugin already before. Here only this plugin was moved.
This plugin could be used in any other repo regardless of the set of other jsdoc plugins used there.

jsdoc-advanced-types-plugin, jsdoc-plugin-intersection, jsdoc-plugin-typescript are not tracking-specific, 3rd party packages. They are not even related to any Ventures/Grow-unique code convention, so I see no reason to pack them under woocommerce-grow-tracking-jsdoc
(Actually, for that reason, I was thinking of moving tilde-alias out of this package, but I'll get back to it later)

---

Have you considered loading a bin in the tool?

Then we can just do:

docs:tracking: woocommerce-grow-tracking-jsdoc ./js/src .jsdocrc.json

I was thinking of it, but in my opinion, it's not worth it. Making it a separate binary/script => tool, has a cost:

• We would need to make sure we forward and support all needed jsdoc features
• A newcomer seeing that could think: "Oh, here is yet another custom tool for that. I need to reed its docs, and learn how it works, and use it." "Can I search in google/stackoverflow when I encounter problems with it?" "Or where do I find some resources within A8C space about it?"
• We would need to answer questions and requests like: "Could woocommerce-grow-tracking-jsdoc generate HTML/support typescript/CoffeeScript?" etc

I assume that some consumers may want to use jsdoc to generate some other things than just tracking docs. (API docs, listing hooks, etc)

When we leave it as docs:tracking: jsdoc ./js/src .jsdocrc.json we just use the existing tool, and make it easier to search for resources and explain what it does and how it works.

---

To keep the benefits mentioned above, but still address the problem of a number of resources I was planning a different thing.
Introduce another package, that would aggregate all plugins and templates we usually use in our repos.

You can think of it as an analogy to eslint:

• woocommerce-grow-tracking-jsdoc - is a one Woo-specific eslint rule; like @woocommerce/dependency-group
• woocommerce-grow-jsdoc (this new package) - is a preset or rules and configs - like @woocommerce/eslint-plugin
• jsdoc is tool we use and install as a dependency; like eslint

[puntope]

so I see no reason to pack them under woocommerce-grow-**tracking**-jsdoc

That way the plugins don't need to load those dependencies in package.json and being generic in the pretty common cases (typescript, usage of jsdoc itself and tilda).

We would need to make sure we forward and support all needed jsdoc features
A newcomer seeing that could think: "Oh, here is yet another custom tool for that. I need to reed its docs, and learn how it works, and use it." "Can I search in google/stackoverflow when I encounter problems with it?" "Or where do I find some resources within A8C space about it?"

I think for that better to implement custom jsdoc directly (without using he tool). I see the tools as a fixed generic convention based on the common between grow projects and with consistency.

We would need to answer questions and requests like: "Could woocommerce-grow-tracking-jsdoc generate HTML/support typescript/CoffeeScript?" etc

I'd suggest to add features in the moment they are pretty common between projects and the conventions dictates so.

In brief I would not be very open with customisation. Since that is what JSDOC itself does. So no need of a tool repo for that since the advantages/cost would be very low.

[tomalec]

That way the plugins don't need to load those dependencies in package.json and being generic in the pretty common cases (typescript, usage of jsdoc itself and tilda).

That's why, as I proposed in the end of the comment above, I'd pack them to another package, like woocommerce-grow-jsdoc (in a separate PR), so the GLA would only have to install that.

[tomalec]

I think for that better to implement custom jsdoc directly (without using he tool). I see the tools as a fixed generic convention based on the common between grow projects and with consistency.

Do I get understand you correctly, that you suggest to make it like:

"doc:tracking": "woocommerce-grow-tracking-jsdoc",
"doc": "woocommerce-grow-something-else-doc",

or

"doc:tracking": "woocommerce-grow tracking-doc",
"storybook": "woocommerce-grow storybook",

?

I think it depends on the overall vision we have for the tools in this repo. If I understand what you suggest it's to have something like an all-in-one solution tailored solely for Grow needs. So as a consumer I'd just do woocommerce-grow storybook without any params any thinking just to generate the storybook, woocommerce-grow- docs to generate all the docs without any params or customization.

I definitely see the benefits of such a solution:

• one entry point
• minimal configuration
• enforced conventions

But I also see the downsides:

• We already have a dev tool that works like the one above: wp-scripts, and instead of implementing yet another swiss army knife, but smaller, I'd rather PR the existing one
• Having a swiss army knife, that's designed to serve only one team doesn't make it generic and shareable at all. That reminds me the problem with woorelease we recently complained about. That such potentially generic tool, was owned by the team that profiled it for only their needs (which is not bad itself), and ignored all the other extensibilities ( which is the bad thing).

My vision is somewhat different. I see this repo as a bag of different, as small as possible tools. Tools that could be seemingly disjointed. But the tools are atomic enough, so they could be easily and quickly iterated on, experimented, plugged in here and there. Then eventually moved to a more generic toolbox, like wp-scripts, woorelease, @woocommerce/{package}. Or maybe even wc-scripts (non existing yet, Woo version of wp-scripts), but not a wc-grow-scripts. Apply Unix philosophy "Write programs that do one thing and do it well", "Choose portability over efficiency"

If we create a new eslint rule it would be easier to get it ported in @woocommerce/ rather than if we'd make custom eslint. If we make a custom jsdoc plugin it's easier to make other projects use jsdoc plugin, than convince someone to use our own jsdoc alternative. Also, if they are using some other doc-generating tool, I bet it's easier to port just this plugin, rather than everything.

Then to address bloated configs, or too many dependencies, we can embrace modularity, and make other packages that solves that problem by using this jsdoc plugin.

[tomalec]

We would need to answer questions and requests like: "Could woocommerce-grow-tracking-jsdoc generate HTML/support typescript/CoffeeScript?" etc

I'd suggest to add features in the moment they are pretty common between projects and the conventions dictates so.

I think you get me wrong. I don't mean to add those features. I mean that when somebody else would think that in their extension, they for some reason need a support for CoffeeScript they would either ask us, or simply assume woocommerce-grow-tracking-jsdoc does not support it, so it won't generate the docs. Whereas that's not the case. As this should be the question "Could jsdoc generate HTML/support TS/CS?" and the answer is already available in Google Search & StackOverflow.

[tomalec]

In brief I would not be very open with customisation. Since that is what JSDOC itself does. So no need of a tool repo for that since the advantages/cost would be very low.

I'm not sure I understand what you mean here.

But if I do, I'd say that's precisely why I'd use jsdoc instead of writing custom/ facade for jsdoc. jsdoc is already customizable and we can use that directly instead of building our own superficial proxy layer.

Similarly to what we did with Storybook. We still use its config (https://github.com/woocommerce/google-listings-and-ads/blob/develop/storybook/main.js#L27-L47) , and configure there:

	Storybook	jsdoc
source files	stories	recurse
.~ convention	webpackFinal config.resolve.alias	woo-grow-tracking-jsdoc/tilde-alias
set of plugins	addons	plugins
language variant	sass support	typescript support

[puntope]

Do I get understand you correctly, that you suggest to make it like:

No, I was talking about the potential need of flexibility and customisation mentioned as an "advantage" of having jsdocs dependencies in the client project against in the tool itself.

So I was referring to these points mentioned in #6 (comment)

We would need to make sure we forward and support all needed jsdoc features
A newcomer seeing that could think: "Oh, here is yet another custom tool for that. I need to reed its docs, and learn how it works, and use it." "Can I search in google/stackoverflow when I encounter problems with it?" "Or where do I find some resources within A8C space about it?"

If thats the need, a consumer can always just implement jsdoc without using our repo :)
I don't think we should forward all the JSDOC options neither serve unconventional use cases.

I think for that better to implement custom jsdoc directly (without using he tool). I see the tools as a fixed generic convention based on the common between grow projects and with consistency.

With this I mean:

"doc:tracking": "woocommerce-grow-tracking-jsdoc", // generates tracking docs in our way (no params accepted)
"storybook": "woocommerce-grow-storybook", //starts storybook, (no params accepted)
.. etc

Why is my concern about having super atomic and customisable tools? Well at the end we will spend more time handling all the potential atomic use cases. In a way that the time spent on the development of the tools could be more expensive than ,for example, just adding our own config and files in the consumer.

Having generics enforces to follow the standards and work in the same way behind Woo Grow umbrella .

"Wanna have the advantages of running doc tracking and storybook in one line dependency?" -> Follow the standard
"Need some unconventional use case?" -> Implement it by your own
"Is the unconventional use case getting common in several projects?" -> Enhance the tool with that use case.

But this is just my opinion which doesn't mean is more or less correct than yours

[puntope]

In brief I would not be very open with customisation. Since that is what JSDOC itself does. So no need of a tool repo for that since the advantages/cost would be very low.

I'm not sure I understand what you mean here.

Kinda the same concept as in #6 (comment)

I'm ok with having config file (sometimes is even not possible to have it in the tool (i.e storybook) But if we can get rid of the deps... why not ?

[puntope]

✅ Im approving this for now but with buts. (im going afk soon and I don't want to be a blocker)

My buts:

• Pending to discuss about name convention with the team (maybe P2) and change the current tools according that name convention in other PR
• Pending to create another tool for loading JSDOC base deps or merging them inside this tool
• I guess it'd be good to discuss about the philosophy behind the tools. Like if we wanna reduce as much as possible the work on the customer side sacrificing flexibility or we want to offer flexibility and customisation by creating a bigger number of atomic tools or increasing work on consumer side.

[puntope]

set of plugins addons plugins

Yes, the difference here and main source of discussion is that the essential add-on dependencies and storybook itself is loaded in the tool, on the other hand, jsdoc lib as well as the essential plugin dependencies are loaded in consumer side.

Storybook only needs 1 dependency + config (plugin/addons deps as well as storybook itself and gh pages are loaded in the tool)
JSDOC tracking needs 1 dependency + config + 1 dependency per plugin loaded + JSDOC dependency

[tomalec]

• Pending to create another tool for loading JSDOC base deps or merging them inside this tool

Storybook only needs 1 dependency + config (plugin/addons deps as well as storybook itself and gh pages are loaded in the tool)
JSDOC tracking needs 1 dependency + config + 1 dependency per plugin loaded + JSDOC dependency

Addressed in #10

[tomalec]

Pending to discuss about name convention with the team (maybe P2) and change the current tools according that name convention in other PR

Separate issue to discuss that: #7

[tomalec]

I guess it'd be good to discuss about the philosophy behind the tools. Like if we wanna reduce as much as possible the work on the customer side sacrificing flexibility or we want to offer flexibility and customisation by creating a bigger number of atomic tools or increasing work on consumer side.

Created a Ventures P2 post