to-do: fix unsupported symbols

iuioiua commented 2 days ago

Background

deno doc doesn't seem to some symbols as a default arguments or @default JSDoc tag values. While this is a runtime issue, we should fix this on our side in the meantime of that being fixed. These symbols come up as [UNSUPPORTED] in documentation, preventing them from being fully understood.

Fix instructions

To fix, remove the default value of an argument, and make that argument optional, if that default value is an object. Then, set the default value within the function body. There are probably other cases that should be considered, but this is likely the main case.

- function foo(arg1: MyInterface = {}) {
+ function foo(arg?: MyInterface) {
+   arg ??= {};

  // ...

  }

The fix can be confirmed by running deno doc --html <script>, then searching for [UNSUPPORTED] within the output in /docs.

Affected APIs

These symbols seem to be affected:

[ ] async/delay
[ ] async/tee
[ ] bytes/lastIndexOfNeedle
[ ] cli/parseArgs
[ ] cli/promptSecret
[ ] collections/joinToString
[ ] collections/slidingWindows
[ ] datetime/DateTimeFormatter.prototype.format
[ ] datetime/format
[ ] datetime/Tokenizer.prototype.tokenize
[ ] dotenv/loadSync
[ ] dotenv/load
[ ] encoding/decodeAscii85
[ ] encoding/encodeAscii85
[ ] encoding/encodeVarint
[ ] expect/iterableEquality
[ ] fmt/format
[ ] fs/copySync
[ ] fs/copy
[ ] fs/expandGlobSync
[ ] fs/expandGlob
[ ] fs/moveSync
[ ] fs/move
[ ] fs/walkSync
[ ] fs/walk
[ ] html/unescape
[ ] http/calculate
[ ] http/mockConn
[ ] http/serveDir
[ ] http/serveFile
[ ] internal/buildMessage
[ ] io/sliceLongToBytes
[ ] io/toReadableStream
[ ] io/toWritableStream
[ ] path/globToRegExp
[ ] path/joinGlobs
[ ] path/normalizeGlob
[ ] semver/checkIdentifier
[ ] semver/compareIdentifier
[ ] streams/Buffer.prototype.bytes
[ ] testing/FakeTime.prototype.delay
[ ] toml/Scanner.prototype.nextUntilChar
[ ] toml/Utils.unflat
[ ] ulid/monotonicUlid
[ ] ulid/ulid
[ ] uuid/generate
[ ] yaml/dump
[ ] yaml/loadDocuments
[ ] yaml/load
[ ] yaml/parseAll
[ ] yaml/parse
[ ] yaml/stringify

kt3k commented 2 days ago

I think we should fix this in deno_doc. There seem too many places to fix.

cc @crowlKats

crowlKats commented 2 days ago

I think we should fix this in deno_doc. There seem too many places to fix.

cc @crowlKats

Yep I agree, this should be fixed upstream rather than circumventing the issue

denoland / deno_std