Comments (7)
This will be a bit much though. For example, in some of my projects I wouldn't have time to go through adding examples for everything:
Ensure all symbols have at least one @example tag.
It would be nice to be able to be able to opt-out of certain rules and deno lint
provides all that functionality already.
from deno.
I guess being forced to document that isn't so bad now that I think about it more.
from deno.
I think it's possible deno doc --lint
users will be fine without opt-out. The command is opt-in and likely used by those who want the best for their documentation. It might be worth expanding deno doc --lint
until we see sufficient evidence of demand for opt-out, which may never come.
from deno.
I talked with @kt3k; he also thinks this might be a good idea.
from deno.
I think we might want to consider moving deno doc --lint
into the deno lint
sub command and only have it active on packages that specify exports
. It would be nice to be able to selectively ignore these rules. For example, I don't want to document all these type parameters in deno std:
export function parseArgs<
TArgs extends Values<
TBooleans,
TStrings,
TCollectable,
TNegatable,
TDefaults,
TAliases
>,
TDoubleDash extends boolean | undefined = undefined,
TBooleans extends BooleanType = undefined,
TStrings extends StringType = undefined,
TCollectable extends Collectable = undefined,
TNegatable extends Negatable = undefined,
TDefaults extends Record<string, unknown> | undefined = undefined,
TAliases extends Aliases<TAliasArgNames, TAliasNames> | undefined = undefined,
TAliasArgNames extends string = string,
TAliasNames extends string = string,
>(
args: string[],
{
"--": doubleDash = false,
alias = {} as NonNullable<TAliases>,
boolean = false,
default: defaults = {} as TDefaults & Defaults<TBooleans, TStrings>,
stopEarly = false,
string = [],
collect = [],
negatable = [],
unknown: unknownFn = (i: string): unknown => i,
}: ParseOptions<
TBooleans,
TStrings,
TCollectable,
TNegatable,
TDefaults,
TAliases,
TDoubleDash
> = {},
): Args<TArgs, TDoubleDash> {
from deno.
Perhaps, running code snippets can be done with deno test --doc
and the rest with deno doc --lint
.
from deno.
Ensure all type parameters are documented with a @typeparam or @template tag.
Ensure all parameters are documented with a @param, @arg, or @argument tag.
Ensure all functions and methods are documented with a @returns tag.
Ensure all symbols have at least one @example tag.
I've worked in several codebases that had strict lints like this, and they end up with a lot of useless boilerplate like:
/**
* Foo the bar according to baz. (Something that makes sense in the problem domain.)
*
* @param foo the foo
* @param bar the bar
* @param baz the baz
* @returns a Value.
*/
function doThing(foo: Foo, bar: Bar, baz: Baz): Value {
👍 for gentle reminders that I forgot to document an exported symbol.
👎 to the above kind of tedium.
Without a way to configure deno doc --lint
's ruleset, adding such rules would probably make me just avoid using it altogether.
from deno.
Related Issues (20)
- self is not defined in NPM packages imported in a Worker HOT 1
- Bug: `deno --help` shows wrong URL HOT 3
- gpujs doesn't work HOT 2
- add progress bar to `deno clean` HOT 1
- test `jupyter::jupyter_kernel_info` is flaky
- Feat: Support formatting sql files with deno fmt
- `Deno has panicked` via `task` command and `package.json` starting version `1.45.3` HOT 8
- Support pglite HOT 7
- Release GitHub Copilot extension for Deno HOT 5
- Feat: shareable presets for formatting and linting
- feat: LSP should suggest `@ts-types` for npm packages with missing types HOT 1
- Implement `PerformanceObserver.observe` from `node:perf_hooks` HOT 1
- Support semver ranges in `deno upgrade --version=`
- DENO_AUTH_TOKEN does not work, when it contains an extra \n at the end HOT 1
- Enable `log` feature of `tracing` crate
- ReadableStream.pipeTo doesn't always work with Deno streams. HOT 5
- add Uint8Array to/from base64 and hex HOT 3
- Feat: New CLI Subcommand - `deno types`
- Deno panics when arguments are logged inside Proxy get handler HOT 4
- Improve error message when accessing /proc
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from deno.