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

docs: add FAQ for linting errors #6157

Open
wants to merge 16 commits into
base: develop
Choose a base branch
from
39 changes: 33 additions & 6 deletions docs/contributing/FAQ.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,8 @@ limitations under the License.
- [How can I set up my development environment to contribute to stdlib?](#setup-dev-environment)
- [How can I install cppcheck?](#install-cppcheck)
- [I am seeing different return values in the JavaScript and C implementation for the same implementation.](#js-vs-c-return-values)
- [What should I do if Markdown linting on my commits fails because my headings exceed the maximum permissible length?](#markdown-heading-length)
- [What should I do if linting on my commits fails because my headings or lines exceed the maximum permissible length?](#markdown-heading-length)
- [What should I do if JavaScript linting on my commits fails because my function exceeds the maximum permissible number of parameters?](#max-params)
- [I have opened a pull request, where can I seek feedback?](#pr-feedback)
- [I need to generate fixtures for my tests. How can I do that, and what are the best references for inspiration?](#generate-fixtures)
- [I am facing a `Shadowed declaration` linting error in my C files, how can I fix it?](#shadowed-declaration)
Expand Down Expand Up @@ -64,8 +65,6 @@ There are primarily two options for setting up your development environment to c

Note: The dev container does not yet support ARM64 architectures. For more information, or if you're interested in adding ARM64 support, you can visit this [issue][devcontainer-issue].

TODO: Modify the dev container setup link to the exact file link once it is merged.

<a name="install-cppcheck"></a>

## How can I install cppcheck?
Expand Down Expand Up @@ -101,15 +100,37 @@ If they pass, adjust the tolerance and add a note to the C tests indicating that

<a name="markdown-heading-length"></a>

## What should I do if Markdown linting on my commits fails because my headings exceed the maximum permissible length?
## What should I do if linting on my commits fails because my headings or lines exceed the maximum permissible length?

Consider whether the heading/line can be shortened by renaming variables (e.g., changing `strideX` to `sx`). If shortening is not possible, disable the lint rule at the top level using:

- For JavaScript files:

Consider whether the heading can be shortened by renaming variables (e.g., changing `strideX` to `sx`). If shortening is not possible, disable the lint rule at the top level using:
```javascript
// eslint-disable-line max-len
```

[Reference Comment][javascript-len-ref]

- For Markdown files:

```markdown
<!-- lint disable maximum-heading-length -->
```

TODO: Can we add a reference PR link?
[Reference Comment][markdown-len-ref]

<a name="markdown-heading-length"></a>

## What should I do if JavaScript linting on my commits fails because my function exceeds the maximum permissible number of parameters?

Consider whether the number of parameters can be reduced. If reduction is not possible, disable the lint rule at the top level using:

```javascript
// eslint-disable-line max-params
```

[Reference Comment][javascript-params-ref]

<a name="pr-feedback"></a>

Expand Down Expand Up @@ -386,6 +407,12 @@ For more `make` commands, refer to the [documentation][benchmark] on running ben

[make-commands]: https://github.com/stdlib-js/stdlib/tree/develop/tools/make/lib

[markdown-len-ref]: https://github.com/stdlib-js/stdlib/blob/78e0cfd8b6c0429a443b07fd39fa9dd53bf44d23/lib/node_modules/%40stdlib/lapack/base/dgttrf/README.md?plain=1#L94

[javascript-len-ref]: https://github.com/stdlib-js/stdlib/blob/78e0cfd8b6c0429a443b07fd39fa9dd53bf44d23/lib/node_modules/%40stdlib/lapack/base/dgttrf/lib/base.js#L111

[javascript-params-ref]: https://github.com/stdlib-js/stdlib/blob/78e0cfd8b6c0429a443b07fd39fa9dd53bf44d23/lib/node_modules/%40stdlib/lapack/base/dgttrf/lib/base.js#L75

</section>

<!-- /.links -->