Skip to content

Commit

Permalink
fix: fix HTTP API docs linter for missing params (farcasterxyz#1687)
Browse files Browse the repository at this point in the history
## Motivation

The HTTP API Doc Linter throws a confusing error when the list of
parameters in an endpoint is missing. Instead, if a new HTTP doc doesn't
specify a list of parameters, assume it's empty.

Example failing lint:
https://github.com/farcasterxyz/hub-monorepo/actions/runs/7819553394/job/21332224262?pr=1630
The error was:
```
@farcaster/hubble:lint:ci: Parameter "event_id" is documented in the parameters table (on events.md:10) for endpoint "currentPeers" but is not specified in the @doc-tag (on httpServer.ts: line 242)
```

The lint error references `events.md` (not relevant to the changeset in
the PR), which was confusing. This was because `foundEndpoint` carried
over between files.

## Change Summary

Small fix to `getParametersForEndpoint` to scope parameters to a file

## Merge Checklist

_Choose all relevant options below by adding an `x` now or at any time
before submitting for review_

- [x] PR title adheres to the [conventional
commits](https://www.conventionalcommits.org/en/v1.0.0/) standard
- [ ] PR has a
[changeset](https://github.com/farcasterxyz/hub-monorepo/blob/main/CONTRIBUTING.md#35-adding-changesets)
- [ ] PR has been tagged with a change label(s) (i.e. documentation,
feature, bugfix, or chore)
- [ ] PR includes
[documentation](https://github.com/farcasterxyz/hub-monorepo/blob/main/CONTRIBUTING.md#32-writing-docs)
if necessary.
- [ ] All [commits have been
signed](https://github.com/farcasterxyz/hub-monorepo/blob/main/CONTRIBUTING.md#22-signing-commits)

## Additional Context


<!-- start pr-codex -->

---

## PR-Codex overview
### Focus of the PR:
Refactoring the `getParametersForEndpoint` function in `httpapidocs.js`
to improve readability and simplify the code structure.

### Detailed summary:
- Replaced nested `forEach` loops with `for...of` loops for better code
readability.
- Removed unnecessary variable initialization and reset.
- Changed variable declaration for `parameters` to `const` for better
code clarity.
- Added comments to explain the purpose of the function.

> ✨ Ask PR-Codex anything about this PR by commenting with `/codex {your
question}`

<!-- end pr-codex -->
  • Loading branch information
kunalmodi authored Feb 24, 2024
1 parent 7176825 commit cc008ce
Showing 1 changed file with 11 additions and 12 deletions.
23 changes: 11 additions & 12 deletions apps/hubble/scripts/httpapidocs.js
Original file line number Diff line number Diff line change
Expand Up @@ -90,28 +90,27 @@ export function httpapidocs() {
}

function getParametersForEndpoint(endpoint, trees) {
let foundEndpoint = false;
let parameters = [];
let line = 0;

trees.forEach(({ fileName, tree }) => {
tree.children.forEach((node, index) => {
// Get the markdown documented parameters for a given endpoint
for (const { fileName, tree } of trees) {
let foundEndpoint = false;
for (const node of tree.children) {
if (node.type === "heading" && node.children[0].value === endpoint) {
foundEndpoint = true;
continue;
}

if (foundEndpoint && node.type === "table") {
parameters = node.children
const parameters = node.children
.slice(1)
.map((row) => row.children[0].children[0]?.value)
.filter((p) => p !== undefined);
line = `${fileName}:${node.position.start.line}`;
foundEndpoint = false; // Reset to stop looking after finding the table
const line = `${fileName}:${node.position.start.line}`;
return { parameters, line};
}
});
});
}
}

return { parameters, line };
return { parameters: [], line: '' };
}

function checkParametersInDocs(docTags, trees) {
Expand Down

0 comments on commit cc008ce

Please sign in to comment.