[Git][ghc/ghc][wip/extensible-interface-files] Change extensible field name version advice

[Josh Meredith]

Josh Meredith pushed to branch wip/extensible-interface-files at Glasgow Haskell Compiler / GHC


Commits:
ee5e88f9 by Josh Meredith at 2020-04-10T20:09:17+10:00
Change extensible field name version advice

- - - - -


1 changed file:

- docs/users_guide/extending_ghc.rst


Changes:

=====================================
docs/users_guide/extending_ghc.rst
=====================================
@@ -760,20 +760,19 @@ GHC's internal ``Binary`` class. The interface to work with these fields is:
     deleteIfaceField :: FieldName -> ModIface -> ModIface
 
 The ``FieldName`` is open-ended, but typically it should contain the producing
-package name, a version number, and the actual field name. For example, a GHC
-Core field might be named like:
+package name, along with the actual field name. Then, the version number can either
+be attached to the serialised data for that field, or in cases where multiple versions
+of a field could exist in the same interface file, included in the field name.
 
-::
-
-    ghc-n.n.n/core
-
-In this example, the version would probably correspond to the package name, but
-a field that changes slower than the package version might associate the version
-with the field:
+Depending on if the field version advances with the package version, or independently,
+the version can be attached to either the package name or the field name. Examples of
+each case:
 
 ::
 
-    example/field-n
+    package/field
+    ghc-n.n.n/core
+    package/field-n
 
 To read an interface file from an external tool without linking to GHC, the format
 is described at `Extensible Interface Files<https://gitlab.haskell.org/ghc/ghc/wikis/Extensible-Interface-Files>`_.



View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/ee5e88f9e131b4949dd2326689c02490322c1f38

-- 
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/ee5e88f9e131b4949dd2326689c02490322c1f38
You're receiving this email because of your account on gitlab.haskell.org.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-commits/attachments/20200410/eb2967d8/attachment-0001.html>