apple / apple/pkl

Document overriding of ValueMapper's builtin converters and type mappings

Open
#1,454 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Java
Stars
11.5k
Forks
402
Avg merge
1d 15h
Merged PRs (30d)
20

Description

Currently it is unclear from the documentation how conversions, converter factories and type mappings can be customized with relation to the built-in ones. For example, I have to do this if I want to create a custom conversion which overrides one of the built-in ones:
```
ValueMapperBuilder.preconfigured()
.addConversions(myCustomConversions) // takes priority over built-in ones
```

but if I want to override a converter factory, I have to do it in a more complicated way:
```
ValueMapperBuilder.unconfigured()
.addConversions(Conversions.all)
.addConverterFactories(myCustomConverterFactories) // takes priority over built-in ones
.addConverterFactories(ConverterFactories.all)
.addTypeMappings(TypeMappings.all)
```
(because, apparently, earlier converter factories have priority over later ones, but later conversions have priority over earlier ones)

Ideally, this behavior should be documented somewhere, and probably unified (so e.g. the shorter form always works, for all types of customizations).

Contributor guide

Open the contributing guide

Research direction

Start with the ValueMapperBuilder examples in the issue and trace how preconfigured(), unconfigured(), addConversions(), addConverterFactories(), and addTypeMappings() determine precedence. Identify the relevant documentation location and document the precedence rules and customization examples; done means users can understand how to override each built-in customization type and whether the behavior is unified.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.