Code-quality review: documentation-only improvements#81
Merged
Conversation
No behavior change; comments only. Build, go vet, staticcheck, golangci-lint and the full -race / -tags debug -race suites are unaffected. - Element queue helpers (SetAttr/SetInner/...): replace the misleading "call only during JawsRender/JawsUpdate" line with the accurate deferred-delivery contract and point to Request.Dirty for the event-driven path; expand the Element.queue chokepoint doc likewise. - contracts.go: fix the dangling [Element.Context]/[Element.Session] doc-links to [Request.Context]/[Request.Session]; give Container.JawsContains a leading synopsis sentence; note the deleted-Element no-op on Renderer.JawsRender and Updater.JawsUpdate. - eventhandler.go: document ErrEventHandlerPanic's Unwrap semantics and that the recorded Type is the UI object type, which may differ from the handler that panicked. - request.go: split Request.Get/Set synopses and add [Session.Get]/[Session.Set] links; document that AlertError also logs; note that Request methods are not nil-safe (unlike Session); record the recycle-window reasoning on appendDirtyTags and the retained-back-pointer/frozen invariant in clearLocked. - broadcast.go: document distributeDirt's deliberate pending-buffer and recycle-window behavior. - jaws.go / session.go: note the CSPRNG panic condition on NewRequest/NewSession. - errvalueunchanged.go: name the JawsSet/JawsSetPath convention that returns it and why the sentinel lives in this package. - element.go: link the public [CallEventHandlers] entry from the appendHandlers note.
392d5b9 to
691316d
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation-only changes from the core-package quality review. Stacked on #80
(based on the
code-quality-reviewbranch); merge after #80. No behavior change —comments only; build, vet, staticcheck, golangci-lint and the full
-race/-tags debug -racesuites are unaffected.SetAttr/SetInner/...): replace the misleading"call only during JawsRender/JawsUpdate" line with the accurate deferred-delivery
contract and point to
Request.Dirtyfor the event-driven path; expand theElement.queuechokepoint doc.[Element.Context]/[Element.Session]doc-links to
[Request.Context]/[Request.Session]; giveContainer.JawsContainsa leading synopsis sentence; note the deleted-Element no-op on
Renderer.JawsRenderand
Updater.JawsUpdate.ErrEventHandlerPanic'sUnwrapsemantics and thatthe recorded
Typeis the UI object type (may differ from the handler that panicked).Request.Get/Setsynopses + add[Session.Get]/[Session.Set]links; document that
AlertErroralso logs; note thatRequestmethods are notnil-safe (unlike
Session); record the recycle-window reasoning onappendDirtyTagsand the retained-back-pointer/
frozeninvariant inclearLocked.distributeDirt's deliberate pending-buffer andrecycle-window behavior.
NewRequest/NewSession.JawsSet/JawsSetPathconvention and why thesentinel lives in this package.
[CallEventHandlers]entry from theappendHandlersnote.