cue: improve documentation for Value.UnifyAccept

[kortschak]

What version of CUE are you using (cue version)?

Not using cue as an executable but rather via the Go API.

$ grep cuelang go.mod                        
	cuelang.org/go v0.6.0-0.dev

Does this issue reproduce with the latest stable release?

Yes

What did you do?

Using the Go API I would like to be able to unify a set of values while ignoring some fields that are only transiently generated but useful to retain for logging purposes.

For example if I have

{
    sum: "a31c34da"
    important1: "value1"
    config: {
        part1: "value2"
    }
} unify ignoring sum {
    sum: "ae20a82c"
    important2: "value3"
}

I would like to be able to resolve this to something like

{
    sum: "a31c34da"|"ae20a82c"
    config: {
        part1: "value2"
    }
    important1: "value1"
    important2: "value3"
}

or similar with the sum field omitted.

It looks to me from the documentation that something like this is supported by cue.Value.UnifyAccept, but how to use it to do this is unclear and I have not been able to get it to work in my experiments. Can the documentation be clarified for this?

What did you expect to see?

Clear explanation of how to use UnifyAccept.

What did you see instead?

Limited explanation. I was able to find one use of it in the tree and no tests, so it is difficult to know how to use it, or even whether my interpretation that it is usable for this is correct.

[myitcv]

I'm not altogether certain there isn't a bug lurking here given that method doesn't have tests.

[myitcv]

Oops, that sent early. Thanks for the report, @kortschak.

[myitcv]

Noting that #454 is, I think, effectively the same as what you would like to achieve in this case.

That said, the UnifyAccept docs appear (per @mpvl) to be wrong. They should be improved, and a test added. Which we will aim to do in v0.6.0.

[kortschak]

Thanks. I'm not sure that #454 does exactly what I was looking for since it requires that fields be missing as opposed to the situation I have where I'd like explicitly not missing and disagreeing fields to be ignored, unless I'm missing something in that proposal for how to do that.