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

feat(lint): check for docblock in public API exports #106

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat(lint): check for docblock in public API exports #106

wants to merge 1 commit into from

Conversation

kalisjoshua
Copy link
Contributor

@kalisjoshua kalisjoshua commented Nov 18, 2024 •
edited by belsrc
Loading

Closes #113

✅ Pull Request Checklist:

  • Included link to corresponding GitHub Issue.
  • The commit message follows conventional commit extended guidelines.
  • Added/updated unit tests and storybook for this change (for bug fixes / features).
  • Added/updated documentation (for bug fixes / features)
  • Filled out test instructions.

📝 Test Instructions:

❓ Does this PR introduce a breaking change?

  • Yes
  • No

💬 Other information

issue #113

@kalisjoshua kalisjoshua force-pushed the feat/103-docblock branch 3 times, most recently from c96f37d to eec16e4 Compare November 19, 2024 13:18
@kalisjoshua kalisjoshua force-pushed the feat/103-docblock branch 4 times, most recently from 7cc34ac to 7c43fb5 Compare November 19, 2024 19:39
@kalisjoshua kalisjoshua linked an issue Nov 19, 2024 that may be closed by this pull request
Audit code docblocks for documentation generation #103
Open
belsrc
belsrc reviewed Nov 20, 2024
View reviewed changes
package.json Outdated
@@ -25,6 +25,7 @@
"indexer": "turbo index",
"license": "pnpm zx scripts/license.mjs",
"lint": "turbo lint",
"postlint": "pnpm zx scripts/docblock.mjs",
Copy link
Contributor

Choose a reason for hiding this comment

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

Can probably just make this part of the lint command so that turbo can cache it.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Does turbo not execute post* script automatically?

Copy link
Contributor

Choose a reason for hiding this comment

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

By natural of it running package commands, it might. But I don't think that it will cache the output which is needed to allow it to "skip" processes that don't need to run again.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

How do we test it to see?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I moved it into lint.

Copy link
Contributor

@belsrc belsrc Dec 2, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

Yea, doing && command still won't cache it in turbo. Need to do something like Adding tasks and then in the actual lint script do something like running multiple. i.e.

"lint": "turbo run lint:code lint:comments",

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I added the task to the turbo config - https://github.com/gohypergiant/standard-toolkit/pull/106/files#diff-f8de965273949793edc0fbfe249bb458c0becde39b2e141db087bcbf5d4ad5e3R10-R13.

scripts/docblock.mjs Outdated
Comment on lines 25 to 47
if (node.type === 'ExportDeclaration') {
if (node.declaration.identifier) {
acc.push(node.declaration.identifier.value);
} else if (node.declaration.declarations) {
for (const inner of node.declaration.declarations) {
acc.push(inner.id.value);
}
}
}
Copy link
Contributor

Choose a reason for hiding this comment

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

Type exports are also declaration.id.value

Copy link
Contributor Author

Choose a reason for hiding this comment

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

For the context - docblock - does it matter? Do we want to expect docblock for type alias'?

Copy link
Contributor

Choose a reason for hiding this comment

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

Yea. Still a part of the public facing API. And, depending on how the type is constructed, intellisense won't help. Unless you "goto definition" several times.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I think I got this fixed. Let me knwo.

scripts/docblock.mjs Outdated Show resolved Hide resolved
@kalisjoshua kalisjoshua changed the title start for docblock check check for docblock in public API exports Nov 22, 2024
@kalisjoshua kalisjoshua changed the title check for docblock in public API exports feat(lint): check for docblock in public API exports Nov 22, 2024
@kalisjoshua kalisjoshua force-pushed the feat/103-docblock branch 2 times, most recently from 7712de1 to 8fe201f Compare December 2, 2024 15:34
@belsrc
Copy link
Contributor

belsrc commented Dec 2, 2024

Additionally, @brandonjpierce, I'm assuming we want this to be per package like normal? For caching reasons.

@belsrc
Copy link
Contributor

belsrc commented Dec 2, 2024

Since it is relevant, this doesn't check for "correctness" does it? It's purely "do I have at least a /** */ above the code?"

@kalisjoshua
Copy link
Contributor Author

Since it is relevant, this doesn't check for "correctness" does it? It's purely "do I have at least a /** */ above the code?"

I thought that was what we talked about? Checking for "correctness" is a deeper rabbit hole; one I am happy to go down if that is what we want.

@belsrc
Copy link
Contributor

belsrc commented Dec 2, 2024

Ok, then let me spin up a new ticket as this doesn't directly address the one linked in the description. As for the second part of your comment, personally I think "probably". I don't know the usefulness of simply checking if there is any comment since I'm assuming /** */ will "pass". Which wouldn't do anything to help us with docs.

@kalisjoshua
Copy link
Contributor Author

Ok, then let me spin up a new ticket as this doesn't directly address the one linked in the description. As for the second part of your comment, personally I think "probably". I don't know the usefulness of simply checking if there is any comment since I'm assuming /** */ will "pass". Which wouldn't do anything to help us with docs.

The ticket doesn't detail what it is looking for. What defines "correctness"?

@belsrc
Copy link
Contributor

belsrc commented Dec 2, 2024 •
edited
Loading

Added #113. Updated this description for link. Clarified in original #103.

To add to that, most of the issues that me and Brandon created were done in like 30min and were aimed towards us. So if there is additional clarity needed for you, please just pop a comment in them. Since you aren't knee deep in the internal project that most of them came from.

@kalisjoshua
Copy link
Contributor Author

If we are just looking for the docblock to have those elements - description and example - then that is easy enough. But executing the examples to check that level of correctness would be more involved.

@kalisjoshua kalisjoshua added the docs Documentation only changes label Dec 23, 2024
@kalisjoshua kalisjoshua added the ci Changes to our CI configuration files and scripts label Dec 23, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@belsrc belsrc belsrc left review comments

@brandonjpierce brandonjpierce Awaiting requested review from brandonjpierce brandonjpierce is a code owner

@ArrayKnight ArrayKnight Awaiting requested review from ArrayKnight ArrayKnight is a code owner

At least 1 approving review is required to merge this pull request.

Assignees
No one assigned
Labels
ci Changes to our CI configuration files and scripts docs Documentation only changes
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Create script to check correctness of docblocks Audit code docblocks for documentation generation
2 participants
@kalisjoshua @belsrc