Add opt-in binding metadata for API documentation - #233
Open
Segfaultd wants to merge 4 commits into
Open
Conversation
* feat: add native binding metadata * test: expand native metadata coverage * fix: align metadata with runtime bindings * feat: streamline documented bindings * fix: restore header-only metadata builds * fix: align documented property runtime shapes
class_::property(get, set) installed the accessor with SetNativeDataProperty, whose setter does not fire when the property is assigned on a derived instance through an inherited prototype -- V8 creates an own data property on the receiver instead of invoking the ancestor setter. Getters walk the chain fine, so only setters on derived types were affected. Register read-write properties as real JS accessors (SetAccessorProperty), whose setter runs through the prototype chain. Read-only properties and direct callback-form properties (that take a v8::PropertyCallbackInfo) keep the SetNativeDataProperty path.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Embedders often need scripting API documentation, TypeScript declarations, or other tooling derived from their V8 bindings. Today that generally requires a second, manually maintained description of the API. That duplicate source drifts from the runtime, and raw V8 callbacks do not expose enough signature or documentation information to reconstruct the intended JavaScript API afterward.
This PR adds an optional, renderer-neutral metadata layer so a binding and its public API description can be declared together. Existing v8pp binding APIs remain available and unchanged; metadata is recorded only when a registry-backed module or class is used.
What this adds
since, and deprecation metadataclass_::ctor<Args...>(), with optional constructor documentation and explicit JavaScript signatures for raw V8 callbacks or native/JS type mismatchesv8pp::moduleandv8pp::class_overloads that install the runtime binding and record its documentation atomicallyDocumented static values are installed on the constructor
FunctionTemplateas accessors backed by v8pp-managed external storage. This avoids prematurely materializing constructors, supports object-valued and writable statics, and works whether a class is published directly or throughmodule::class_().Additional fix: read-write property setters through inherited prototypes
class_::property(name, get, set)installed the accessor withSetNativeDataProperty, whose setter does not fire when the property is assigned on a derived instance through an inherited prototype: V8 creates an own data property on the receiver instead of invoking the ancestor setter. Getters walk the prototype chain correctly, so only setters were affected, and only on classes thatinherit<Base>()a base which declares a read-write property.This PR now registers accessor-compatible read-write properties as real JS accessors via
SetAccessorProperty, whose setter runs through the prototype chain. Read-only properties and direct callback-form getters/setters (those taking av8::PropertyCallbackInfo) keep theSetNativeDataPropertypath, so behavior for non-inherited and read-only properties is unchanged.Compatibility
#cmakedefine01, fixing the existingON/OFFpreprocessor mismatch exposed by the supported CI matrix.Validation
class_::ctorbehavior are covered by native testsactionlintpasses for the updated workflowExample
The exported JSON is intentionally presentation-agnostic so downstream projects can produce HTML, declarations, editor data, or other formats without coupling those generators to v8pp.