[go] structs: improve doc comment for HostLayout

7 views
Skip to first unread message

David Chase (Gerrit)

unread,
Mar 23, 2025, 10:42:18 PMMar 23
to goph...@pubsubhelper.golang.org, golang-co...@googlegroups.com

David Chase has uploaded the change for review

Commit message

structs: improve doc comment for HostLayout

Make it clear(er) that normal Go programmers don't need to
worry about this.
Change-Id: I070c2af7701531ffba5655d4bfe92653bcd9514d

Change diff

diff --git a/src/structs/doc.go b/src/structs/doc.go
index ec79490..84f610a 100644
--- a/src/structs/doc.go
+++ b/src/structs/doc.go
@@ -3,8 +3,10 @@
 // license that can be found in the LICENSE file.
 
 // Package structs defines marker types that can be used as struct fields
-// to modify the properties of a struct.
+// to modify the properties of a struct in certain special cases.
 //
 // By convention, a marker type should be used as the type of a field
 // named "_", placed at the beginning of a struct type definition.
+//
+// These tags ought to be very rare in "normal" Go code.
 package structs
diff --git a/src/structs/hostlayout.go b/src/structs/hostlayout.go
index d373f24..6e22250 100644
--- a/src/structs/hostlayout.go
+++ b/src/structs/hostlayout.go
@@ -14,6 +14,20 @@
 //
 // By convention, HostLayout should be used as the type of a field
 // named "_", placed at the beginning of the struct type definition.
+//
+// HostLayout should be used in types that are passed to, returned from,
+// or accessed via a pointer passed to/from host APIs. Without this marker,
+// struct layout order is not guaranteed by the language spec, though up to
+// and including Go 1.23 the host and language layouts happen to match.
+// For example, syscall.fdstat in fs_wasip1.go needs to specify host layout:
+//
+//	type fdstat struct {
+//		_                structs.HostLayout
+//		filetype         filetype
+//		fdflags          uint16
+//		rightsBase       rights
+//		rightsInheriting rights
+//	}
 type HostLayout struct {
 	_ hostLayout // prevent accidental conversion with plain struct{}
 }

Change information

Files:
  • M src/structs/doc.go
  • M src/structs/hostlayout.go
Change size: S
Delta: 2 files changed, 17 insertions(+), 1 deletion(-)
Open in Gerrit

Related details

Attention set is empty
Submit Requirements:
  • requirement is not satisfiedCode-Review
  • requirement satisfiedNo-Unresolved-Comments
  • requirement is not satisfiedReview-Enforcement
  • requirement is not satisfiedTryBots-Pass
Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. DiffyGerrit
Gerrit-MessageType: newchange
Gerrit-Project: go
Gerrit-Branch: master
Gerrit-Change-Id: I070c2af7701531ffba5655d4bfe92653bcd9514d
Gerrit-Change-Number: 660275
Gerrit-PatchSet: 1
Gerrit-Owner: David Chase <drc...@google.com>
unsatisfied_requirement
satisfied_requirement
open
diffy

Ian Lance Taylor (Gerrit)

unread,
Oct 30, 2025, 8:04:07 PMOct 30
to David Chase, goph...@pubsubhelper.golang.org, Ian Lance Taylor, golang-co...@googlegroups.com
Attention needed from David Chase

Ian Lance Taylor voted Code-Review+2

Code-Review+2
Open in Gerrit

Related details

Attention is currently required from:
  • David Chase
Submit Requirements:
  • requirement satisfiedCode-Review
  • requirement satisfiedNo-Unresolved-Comments
  • requirement is not satisfiedReview-Enforcement
  • requirement is not satisfiedTryBots-Pass
Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. DiffyGerrit
Gerrit-MessageType: comment
Gerrit-Project: go
Gerrit-Branch: master
Gerrit-Change-Id: I070c2af7701531ffba5655d4bfe92653bcd9514d
Gerrit-Change-Number: 660275
Gerrit-PatchSet: 2
Gerrit-Owner: David Chase <drc...@google.com>
Gerrit-Reviewer: Ian Lance Taylor <ia...@golang.org>
Gerrit-Attention: David Chase <drc...@google.com>
Gerrit-Comment-Date: Fri, 31 Oct 2025 00:04:03 +0000
Gerrit-HasComments: No
Gerrit-Has-Labels: Yes
satisfied_requirement
unsatisfied_requirement
open
diffy

Cherry Mui (Gerrit)

unread,
Nov 25, 2025, 11:01:31 AM (4 days ago) Nov 25
to David Chase, goph...@pubsubhelper.golang.org, Go LUCI, Ian Lance Taylor, golang-co...@googlegroups.com
Attention needed from David Chase

Cherry Mui voted Code-Review+1

Code-Review+1
Open in Gerrit

Related details

Attention is currently required from:
  • David Chase
Submit Requirements:
    • requirement satisfiedCode-Review
    • requirement satisfiedNo-Unresolved-Comments
    • requirement satisfiedReview-Enforcement
    • requirement satisfiedTryBots-Pass
    Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. DiffyGerrit
    Gerrit-MessageType: comment
    Gerrit-Project: go
    Gerrit-Branch: master
    Gerrit-Change-Id: I070c2af7701531ffba5655d4bfe92653bcd9514d
    Gerrit-Change-Number: 660275
    Gerrit-PatchSet: 3
    Gerrit-Owner: David Chase <drc...@google.com>
    Gerrit-Reviewer: Cherry Mui <cher...@google.com>
    Gerrit-Reviewer: David Chase <drc...@google.com>
    Gerrit-Reviewer: Ian Lance Taylor <ia...@golang.org>
    Gerrit-Attention: David Chase <drc...@google.com>
    Gerrit-Comment-Date: Tue, 25 Nov 2025 16:01:26 +0000
    Gerrit-HasComments: No
    Gerrit-Has-Labels: Yes
    satisfied_requirement
    open
    diffy

    David Chase (Gerrit)

    unread,
    Nov 26, 2025, 4:10:55 PM (3 days ago) Nov 26
    to goph...@pubsubhelper.golang.org, golang-co...@googlegroups.com
    Attention needed from David Chase

    David Chase uploaded new patchset

    David Chase uploaded patch set #4 to this change.
    Following approvals got outdated and were removed:
    • TryBots-Pass: LUCI-TryBot-Result+1 by Go LUCI
    Open in Gerrit

    Related details

    Attention is currently required from:
    • David Chase
    Submit Requirements:
      • requirement satisfiedCode-Review
      • requirement satisfiedNo-Unresolved-Comments
      • requirement satisfiedReview-Enforcement
      • requirement is not satisfiedTryBots-Pass
      Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. DiffyGerrit
      Gerrit-MessageType: newpatchset
      Gerrit-Project: go
      Gerrit-Branch: master
      Gerrit-Change-Id: I070c2af7701531ffba5655d4bfe92653bcd9514d
      Gerrit-Change-Number: 660275
      Gerrit-PatchSet: 4
      satisfied_requirement
      unsatisfied_requirement
      open
      diffy

      David Chase (Gerrit)

      unread,
      Nov 26, 2025, 11:49:29 PM (3 days ago) Nov 26
      to goph...@pubsubhelper.golang.org, golang-co...@googlegroups.com
      Attention needed from David Chase

      David Chase uploaded new patchset

      David Chase uploaded patch set #5 to this change.
      Following approvals got outdated and were removed:
      • TryBots-Pass: LUCI-TryBot-Result+1 by Go LUCI
      Open in Gerrit

      Related details

      Attention is currently required from:
      • David Chase
      Submit Requirements:
      • requirement satisfiedCode-Review
      • requirement satisfiedNo-Unresolved-Comments
      • requirement satisfiedReview-Enforcement
      • requirement is not satisfiedTryBots-Pass
      Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. DiffyGerrit
      Gerrit-MessageType: newpatchset
      Gerrit-Project: go
      Gerrit-Branch: master
      Gerrit-Change-Id: I070c2af7701531ffba5655d4bfe92653bcd9514d
      Gerrit-Change-Number: 660275
      Gerrit-PatchSet: 5
      satisfied_requirement
      unsatisfied_requirement
      open
      diffy
      Reply all
      Reply to author
      Forward
      0 new messages