1989239 - Add a comment section about the structured clone data persists across versions, and sprinkle references to the comment to related code

Status: NEW

(Core :: JavaScript Engine, enhancement, P3)

Description

[Tooru Fujisawa [:arai]]

So, we have a comment that says the structured clone data format cannot be changed,
which comes from the fact that we save the serialized data into disk and use it across versions,
as part of local storage or something along that line.

https://searchfox.org/firefox-main/rev/d5770dd3a8e0c22c71c8b283831ff6f410d5ff05/js/public/RegExpFlags.h#29-31

// Flag-bit values appear in XDR and structured clone data formats, so none of
// these values can be changed (including to assign values in numerically
// ascending order) unless you also add a translation layer.

It would be nice to add a dedicate SMDOC that covers:

• How and where the structured clone data, epecially the serialized format, is used
• What the restrictions are and where they come from (explain the local storage usage)
• The details around the versioning and migration (or the reference to the comment if there's any)

And also add references to the SMDOC to the related code, such as the RegExpFlag class above, to make it easier to follow.

Comment 1

[Jan de Mooij [:jandem]]

I think these comments are a good starting point for turning into an SMDOC comment :)

edit: included more comments

Comment 2

[Steve Fink [:sfink] [:s:]]

Yes, those are the comments I was thinking of. Good thing you left off the comment just before, though, since it sort of implies that these clones are not stored persistently!

I'll do a rewrite pass and turn it into an SMDOC. Thanks, both of you!