Mapper: Comments on fields of bean types

[ljacqu]

Should we support @Comment on bean fields? This might be difficult since we don't always have a direct path (maps with unknown keys) and the comment would be present for each entry.

[sgdc3]

Yeah this should be supported

[ljacqu]

If you have any good use cases, please post them. Definitely one of the bigger things missing, I'd just like to have some good examples to think about how this feature would look in detail

[sgdc3]

I think @gamerover98 might have some specific examples

[gamerover98]

Hello, this is a piece of my configuration where I've used the bean implementation:

TeamProperty class:

 public static class TeamProperty implements ParameterizedType {

	private static final Type[] TYPE_ARGUMENTS = {
		String.class,  //id
		String.class,  //name
		String.class,  //chat color
		DyeColor.class //dye color
	};

	private String    key;
	private String    name;
	private ChatColor chatColor;
	private DyeColor  dyeColor;

	@SuppressWarnings("unused")
	public TeamProperty() {
		// nothing to do
	}

	public TeamProperty(@NotNull String key, @NotNull String name,
			    @NotNull ChatColor chatColor, @NotNull DyeColor dyeColor) {

		this.key       = key;
		this.name      = name;
		this.chatColor = chatColor;
		this.dyeColor  = dyeColor;

	}

	@Override
	public Type[] getActualTypeArguments() {
		return TYPE_ARGUMENTS;
	}

	@Override
	public Type getRawType() {
		return TeamProperty.class;
	}

	@Override
	public Type getOwnerType() {
		return null;
	}

}

BeanPropertyType implementation:

public static class TeamPropertyType extends BeanPropertyType<TeamProperty> {

        private static final Type TYPE = new TeamProperty();

	public TeamPropertyType() {
		super(new TypeInformation(TYPE), DefaultMapper.getInstance());
	}

}

In addition, I've implemented it into a SettingsManager class with a property array:

public class TeamsHolder implements SettingsHolder {

    private static final Type TYPE = new TeamProperty();

    private static final String TEAMS_VALUE = "teams";

    public static final Property<TeamProperty[]> TEAMS;

    static {

        TeamProperty[] defaultTeamPropertyArray = new TeamProperty[] {
                new TeamProperty("RED",  "red",  ChatColor.RED,       DyeColor.RED),
                new TeamProperty("BLUE", "blue", ChatColor.DARK_BLUE, DyeColor.BLUE)
        };

        TEAMS = new PropertyBuilder.ArrayPropertyBuilder<>(new TeamPropertyType(), TeamProperty[] :: new)
                .path(TEAMS_VALUE)
                .defaultValue(defaultTeamPropertyArray)
                .build();

    }

}

This is the result:

teams: 
- key: RED
  name: red
  chatColor: RED
  dyeColor: RED
- key: BLUE
  name: blue
  chatColor: DARK_BLUE
  dyeColor: BLUE

I want to add comments like:

teams: 
  #The team key
- key: RED
  #The team name that...
  name: red
  #Chat color messages...
  chatColor: RED
  #The armor leather color
  dyeColor: RED

Thank you for asking

[gamerover98]

Heard anything? 😌

[ljacqu]

This is really good input, thanks. The reason I tend to forget about this issue is that I'm still unclear on how we'd handle multiple entries in the array.
Need a way to define whether comments should be put on every entry or only on the first. Maybe an optional config on @Comment, except I don't like that the option would then also be available on properties (where it makes no sense). An additional annotation isn't much better since it's hard to name it and the problem, at its core, remains (someone could get confused and use the other annotation on property fields).
Tentatively scheduling this for the next major release since IMHO it is still something that's missing from a complete feature set. 😞 I'm a little paralyzed by indecision on the design.

[ljacqu]

I've been thinking about this a lot, and I think it would be interesting to be able to define comments based on the property values. This would be helpful for #132, but also here. Before exporting, some method could be called that collects @Comment annotations, incl. bean properties. Probably add an option to @Comment to define whether it should appear once or many times. I don't see a more straightforward way.
I will now see how to best have such a method but also make sure that bean properties just automatically get comments registered if they have an @Comment annotation on any fields. Maybe I'm barking up the wrong tree with the idea of defining comments just before an export happens, but I think it would open the door for other things (like the linked issue).