document the reason for 'edit' vs. 'update' operations in field and entity access operation name

Yes, seems like madness. But given the way these handlers are typically coded using switch statements, I can't see how to fix it in a BC way.

This just bit me :(

For BC, what if we did:

D10: access handlers must add support the new operation verb, but calling it is not part of the API yet
D11: calling with the new verb becomes allowed

Or alternatively, do the new method trick:

D10: add accessNew() which uses the 'edit' verb and just calls access(), deprecate access()
D11: remove access()
D12: deprecate accessNew(), re-add access() which is identical just better-named.

The reason those are different is that field level access doesn't make a difference between create or update, while entity level access does.

Ohhhhh.

That makes sense. But it would be nice to document that somewhere.

I'll write something for this.

Updated IS with MR suggestion from #5

I'm triaging RTBC issues → . I read the IS and the comments. I didn't find any unanswered questions or other work to do.

I applied the change and read the added documentation. I am not familiar with field and entity access but it just raised more questions for me. I am thinking that this, with more detail, would be better in the Interface docs. Maybe?

Although, leaving at RTBC because this is an improvement.

I meant to trim the title.

Although, the title says this is to clarify 'edit' and 'update'. The new text does not refer to 'edit' at all.

I guess you meant it doesn't refer to "update"? I think that's OK, explicitly mentioning that might just confuse people who don't read that properly and just go for the keywords.

Text seems OK to me, but I'm not really the best person to decide on clarity of documentation :)

In regards to "better on the interface", fieldAccess() is quite separate from the other access methods which are more about entity-level access, so I think keeping that separate makes sense.

That said, if this raises more questions for you than it answers, maybe put them in the issue then we can see if we can fix that :)

@Berdir, thanks for the helpful explanation.

I am having one of those days - I can't seem to put my questions into words and belatedly I think that the whole comment should be wrapped.

Setting to NW for someone to accept the change.

Seems OK :)

> I think that's OK, explicitly mentioning that might just confuse people who don't read that properly and just go for the keywords.

Yes, I deliberately avoided mentioning 'update' for that reason.

> In regards to "better on the interface", fieldAccess() is quite separate from the other access methods which are more about entity-level access, so I think keeping that separate makes sense.

Yes - fieldAccess() is also fairly specialised. Most people will use entity access, so I've not put this on the interface docblock because most people reading that don't need to know about fieldAccess().

Applied the wrapping fix suggested by @quietone.

lauriii → closed merge request !4693

Committed 9059bd7 and pushed to 11.x. Cherry-picked to 10.1.x as a docs improvement. Thanks!

Automatically closed - issue fixed for 2 weeks with no activity.