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

feat: rework docs api #166

Merged
merged 1 commit into from Jul 6, 2023
Merged

feat: rework docs api #166

merged 1 commit into from Jul 6, 2023

Conversation

tjjfvi
Copy link
Owner

@tjjfvi tjjfvi commented Jul 6, 2023

Before, docs were a builtin part of the metadata, and added like so:

const $bar = $.withMetadata(
  $.docs("lalala"),
  $foo,
)

This generally made the metadata harder to consume.

Now, the docs are not specialized at all. They're simply another codec factory:

const $bar = $.documented(
  "lalala",
  $foo,
)

This codec factory is designed such that the resultant codec has both the metadata of $.documented and the metadata corresponding to the original $foo. This means that CodecVisitors will ignore $.documented by default:

new $.CodecVisitor<string>()
  .add($foo, () => "$foo")
  .visit($bar) // "$foo"

However, you can explicitly opt-in to using $.documented:

new $.CodecVisitor<string>()
  .add($foo, () => "$foo")
  .add($.documented, (_codec, docs) => docs)
  .visit($bar) // "lalala"

This $.documented can be written entirely in user-land (in contrast to the last approach), but we include it here for standardization. However, users can write similar codec factories if they'd like to attach other miscellaneous metadata.

Resolves #136

@tjjfvi tjjfvi merged commit dd4297d into main Jul 6, 2023
3 checks passed
@tjjfvi tjjfvi deleted the new-docs-api branch July 6, 2023 13:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

print docs in inspect
2 participants