comments: prune what the code and plans already say
One line said six times, a stale sig, a block that ran twice — the plans already argued it, so a pointer's the price. Two twenty-six lines cut and not one of them code; four sixty-eight still green, and no type error showed. Assisted-by: Claude Opus 5 via Claude Code
diff --git a/lib/pro_tacts/admin/contacts_edit.rb b/lib/pro_tacts/admin/contacts_edit.rb
index a6642d2..a2aa367 100644
--- a/lib/pro_tacts/admin/contacts_edit.rb
+++ b/lib/pro_tacts/admin/contacts_edit.rb
@@ -87,10 +87,8 @@ module ProTacts
def initialize(contact:, notice: nil)
@contact = contact
# The rows are the contact's own, never what a group lends it
- # (Contact#own): a row here is a row the save may rewrite or
- # remove, and neither is this screen's to do to a value the
- # household owns — the details page is where an inherited row
- # is read (Admin::ContactsShow). The etag below is still the
+ # (Contact#own); the details page is where an inherited row is
+ # read (Admin::ContactsShow). The etag below is still the
# composed contact's, the one a save is guarded against.
@own = contact.own
@notice = notice
@@ -276,21 +274,15 @@ module ProTacts
end
end
- # The birthday row: the one row that saves to the model rather
- # than the card's bytes (docs/plans/2026-09-07-web-birthday-editor.md)
- # — a partial date has no vCard 3.0 spelling, so there is no
- # line to address and the prefill is the model
- # (Contact#birthday), not a reading off the card. It renders
- # only over a held birthday: an empty row was an attribute
- # rendering nothing (docs/DESIGN.md), and the way a birthday
- # arrives is the add dialog's, like every other property. A
- # blank component is an absence and three blanks remove the
- # birthday, the form's blank-equals-absent; a day without its
- # month is refused at the save, the grammar's own rule. Every
- # shape the grammar admits is editable, including the ones no
- # client renders — they live here and go nowhere, their
- # documented fate. Every standing row holds a birthday, so
- # the removal state rides on it unconditionally.
+ # The one row that saves to the model rather than the card's
+ # bytes, so the prefill is Contact#birthday and not a reading
+ # off the card — why, and why every shape the grammar admits is
+ # editable here, is docs/plans/2026-09-07-web-birthday-editor.md.
+ # It renders only over a held birthday: an empty row was an
+ # attribute rendering nothing (docs/DESIGN.md), and a birthday
+ # arrives through the add dialog like every other property. Every
+ # standing row holds one, so the removal state rides on it
+ # unconditionally.
#: () -> void
def birthday_row
birthday = @contact.birthday
@@ -318,15 +310,12 @@ module ProTacts
end
end
- # The birthday row's three controls, shared by the standing
- # row and the add dialog's — month-day-year to match the prose
- # Birthday#to_s renders; a select for the month because a name
- # is the friendlier read and constrains the value by
- # construction, number inputs with native ranges for the day
- # and year. The same names for both callers is the point: a
- # birthday needs no digest, there being at most one, and the
- # save reads either caller's row identically. A nil birthday
- # is the added row — nothing selected, nothing prefilled.
+ # The birthday row's three controls, shared by the standing row
+ # and the add dialog's — the control choices and their order are
+ # docs/plans/2026-09-07-web-birthday-editor.md, "The row". The
+ # same names for both callers is the point: a birthday needs no
+ # digest, there being at most one, and the save reads either
+ # caller's row identically. A nil birthday is the added row.
#: (Birthday? birthday, ?focus: bool) -> void
def birthday_controls(birthday, focus: false)
select(name: "birthday[month]", aria_label: "month",
@@ -439,11 +428,9 @@ module ProTacts
end
end
- # The dialog's list: everything the save can insert, minus a
- # birthday the contact already holds — one being the most a
- # card carries, and the dialog naming only what can still be
- # added. The row is the same guard from the other side,
- # rendering only over a held birthday.
+ # A birthday leaves the list once the contact holds one, that
+ # being the most a card carries. #birthday_row is the same guard
+ # from the other side.
#: () -> Array[String]
def addable_types
@contact.birthday ? ADDABLE_TYPES - ["birthday"] : ADDABLE_TYPES
diff --git a/lib/pro_tacts/admin/contacts_show.rb b/lib/pro_tacts/admin/contacts_show.rb
index ab44fb3..7850ea9 100644
--- a/lib/pro_tacts/admin/contacts_show.rb
+++ b/lib/pro_tacts/admin/contacts_show.rb
@@ -154,10 +154,9 @@ module ProTacts
end
end
- # The stored card for display: byte for byte, except a value — a
- # property's or a parameter's — long enough to be a wall, which
- # renders as its octet count. The count says exactly what is
- # there; what it stands in for is not readable text.
+ # The stored card for display: byte for byte, except a value long
+ # enough to be a wall. The count says exactly what is there; what
+ # it stands in for is not readable text.
#: () -> String
def raw_card
@contact.vcard.lines.map { elide(it) }.join
@@ -184,8 +183,6 @@ module ProTacts
"#{[header, *params].join(';')}:#{count_octets(property.value)}#{terminator}"
end
- # A value over the threshold stands in as its octet count;
- # anything shorter renders as it is.
#: (String value) -> String
def count_octets(value)
value.bytesize > ELIDE_ABOVE ? "[#{value.bytesize} octets elided]" : value
diff --git a/lib/pro_tacts/birthday.rb b/lib/pro_tacts/birthday.rb
index beb8173..f34a153 100644
--- a/lib/pro_tacts/birthday.rb
+++ b/lib/pro_tacts/birthday.rb
@@ -15,14 +15,11 @@ module ProTacts
# alone follows from its allowance of ISO 8601 truncated representation
# f), which it references but does not spell out.
#
- # vCard 3.0 cannot carry any of this: RFC 2425 section 5.8.4 defines
- # the date value as `date-fullyear ["-"] date-month ["-"] date-mday`
- # with all three components required, and RFC 2426 section 3.1.5 builds
- # BDAY on it. So a birthday is database state that no stored card
- # carries, composed into the served card on read and subtracted out of
- # a submitted one on write — Store owns that surgery, over the card
- # VCard reads and the property-level reading below; the full reasoning
- # is docs/plans/2026-08-31-partial-birthdays.md and
+ # vCard 3.0 cannot carry any of this, so a birthday is database state
+ # that no stored card carries, composed into the served card on read
+ # and subtracted out of a submitted one on write — Store owns that
+ # surgery. Why it cannot live in the card, and what each shape puts
+ # on the wire, are docs/plans/2026-08-31-partial-birthdays.md and
# docs/plans/2026-09-01-birthdays-across-a-rewrite.md.
#
# The signature lives in sig/pro_tacts/birthday.rbs: a Data class has
diff --git a/lib/pro_tacts/contact.rb b/lib/pro_tacts/contact.rb
index ef451e8..7396880 100644
--- a/lib/pro_tacts/contact.rb
+++ b/lib/pro_tacts/contact.rb
@@ -167,11 +167,9 @@ module ProTacts
@vcard = line ? card.insert([line]) : card
end
- # The same contact with nothing its groups lend it: the stored
- # card and the birthday, no inheritance. The editor's subject —
- # a form rendered from the composed contact offers rows the member
- # does not own, and saving one writes the group's value into the
- # member's own card (Web#edited_card), which is the
+ # The same contact with nothing its groups lend it: the editor's
+ # subject, because a form rendered from the composed contact would
+ # save a group's value into the member's own card — the
# materialization the composition exists to avoid
# (docs/plans/2026-08-24-vcard-storage-and-groups.md). The etag is
# not this contact's: a screen guarding a save still carries the
@@ -184,8 +182,6 @@ module ProTacts
@own = self.class.new(id: @id, stored: @stored, birthday: @birthday, inherited: [])
end
- # The etag over #vcard's bytes, derived here on first ask and
- # memoized with the card it hashes.
#: () -> String
def etag
return @etag if defined?(@etag)
@@ -249,12 +245,8 @@ module ProTacts
Photo.new(mime_type: signature.fetch(1), bytes:)
end
- # The card's properties — the substrate the typed accessors sit on,
- # and the read for what none of them models. Every line that read,
- # and no complaint about one that did not: a contact is served from
- # its bytes, so a line this parser cannot read costs an accessor its
- # answer and costs the contact nothing. There is no repair to make
- # and nobody to make it, which is why nothing here looks for one.
+ # The substrate the typed accessors sit on, and the read for what
+ # none of them models.
#: () -> Array[VCard::Parser::Property]
def properties = vcard.properties
diff --git a/lib/pro_tacts/store.rb b/lib/pro_tacts/store.rb
index bc6cab6..f1a7a85 100644
--- a/lib/pro_tacts/store.rb
+++ b/lib/pro_tacts/store.rb
@@ -302,18 +302,12 @@ module ProTacts
contact
end
- # The store's own editor changed a contact: upsert the card's
- # bytes and the birthday beside it, reindex, and record one
- # change-log entry carrying the composed etag a client would
- # download — the served card moves when either half moves, so one
- # save is one entry however it split between them. Not #put, which
- # answers a client's submission and reads a BDAY-less card as a
- # birthday the client dropped (its rewrite arm deletes the model
- # row accordingly): an editor's save carries no BDAY line by
- # construction, so running it through put would delete every
- # edited contact's birthday. rewrite's card input is the stored
- # one by definition, and the birthday passed beside it is the
- # model's whole new state — an upsert or a delete, never a splice
+ # The store's own editor changed a contact, against #put's "a
+ # client submitted a card" — why the two paths cannot be one is
+ # docs/plans/2026-09-05-web-card-editor.md, "Two write paths
+ # through the store". The card input is the stored one by
+ # definition, and `birthday:` is the model's whole new state, an
+ # upsert or a delete, never a splice
# (docs/plans/2026-09-07-web-birthday-editor.md).
#: (String id, String vcard, birthday: Birthday?) -> Contact
def rewrite(id, vcard, birthday:)
@@ -330,8 +324,8 @@ module ProTacts
contact
end
- # Removes a card, leaving the tombstone that tells a syncing client
- # it is gone. Returns whether there was anything to remove.
+ # Removes a card, leaving the change-log entry that tells a syncing
+ # client it is gone.
#: (String id) -> bool
def delete(id)
@database.transaction do
diff --git a/lib/pro_tacts/vcard.rb b/lib/pro_tacts/vcard.rb
index b21978f..887c8a0 100644
--- a/lib/pro_tacts/vcard.rb
+++ b/lib/pro_tacts/vcard.rb
@@ -157,9 +157,8 @@ module ProTacts
properties.any? { it.name.casecmp?("VERSION") }
end
- # The value of the card's UID property, if it carries one. Names
- # compare without case, as the index's NOCASE collation already
- # assumes for them.
+ # Names compare without case, as the index's NOCASE collation
+ # already assumes for them.
#: () -> String?
def uid
properties.find { it.name.casecmp?("UID") }&.value
@@ -176,7 +175,6 @@ module ProTacts
[taken, VCard.new(rest.map(&:verbatim).join)]
end
- # The card's bytes, exactly as it was given them.
#: () -> String
def to_s = @bytes
diff --git a/lib/pro_tacts/vcard/parser.rb b/lib/pro_tacts/vcard/parser.rb
index 36cafa1..c2e15ee 100644
--- a/lib/pro_tacts/vcard/parser.rb
+++ b/lib/pro_tacts/vcard/parser.rb
@@ -133,13 +133,11 @@ module ProTacts
#: () -> bool
def unreadable? = !error.nil? && !broke_assumption?
- # The line's address for a save that names it: the SHA-256 of
- # the verbatim bytes, folds and terminator included — constant
- # size, pure ASCII, and no card content hidden in the page
- # (docs/plans/2026-09-05-web-card-editor.md). Stable across
- # the render-to-save cycle the snapshot guard certifies, and
- # blind otherwise: identical bytes digest alike, which is the
- # one pair of lines no address can tell apart.
+ # The line's address for a save that names it, over the
+ # verbatim bytes, folds and terminator included — why a digest
+ # and not the bytes is docs/plans/2026-09-05-web-card-editor.md.
+ # Blind to one thing: identical bytes digest alike, which is
+ # the one pair of lines no address can tell apart.
#: () -> String
def digest = Digest::SHA256.hexdigest(verbatim)
end
@@ -209,9 +207,7 @@ module ProTacts
line.gsub(FOLD, "")
end
- # One logical line into a Line: the content line it read, or the
- # error the failure raised. A blank line is neither: no property,
- # no error.
+ # A blank line is neither a property nor an error.
#: (String logical_line) -> Line
def self.line_of(logical_line)
Line.new(property: new(logical_line).parse, verbatim: logical_line, error: nil)
@@ -318,7 +314,6 @@ module ProTacts
@scanner.scan(PTEXT).to_s
end
- # Where the scan gave up, for the message that says so.
#: () -> String
def here
"at offset #{@scanner.pos}"
diff --git a/lib/pro_tacts/web.rb b/lib/pro_tacts/web.rb
index 3cfa0f4..73a6c98 100644
--- a/lib/pro_tacts/web.rb
+++ b/lib/pro_tacts/web.rb
@@ -154,7 +154,6 @@ module ProTacts
end
end
- # The edit's apply, under the same fall-through-to-404 rule.
r.post do
apply_edit(r, id)
end
@@ -168,9 +167,8 @@ module ProTacts
r.get "photo" do
contact = store.contact(id)
- # A contact with no picture a browser can show is no
- # match here, same fall-through-to-404 as the page below —
- # the views never point at a photo the card lacks.
+ # The views never point at a photo the card lacks, so a
+ # contact with none is the 404 case above.
if contact && (photo = contact.photo)
response["Content-Type"] = photo.mime_type
response["ETag"] = contact.etag
@@ -181,8 +179,6 @@ module ProTacts
r.get do
contact = store.contact(id)
- # No match falls through to the empty-body 404 the
- # not_found handler fills in, same as the CardDAV GET.
if contact
response["Content-Type"] = "text/html; charset=utf-8"
Admin::ContactsShow.call(contact:)
@@ -308,9 +304,8 @@ module ProTacts
etag_only = body.include?("getetag") && !body.include?("displayname") && !body.include?("resourcetype")
- # Etag-only asks want the members; the collection self-entry
- # is omitted until a client is found to need it. Full property
- # requests (Depth:0 collection info) get the collection entry.
+ # The collection self-entry is omitted from an etag-only ask
+ # until a client is found to need it.
collection_response = ""
unless etag_only
# Every property in this body and where it comes from:
@@ -363,7 +358,6 @@ module ProTacts
XML
end
- # Depth: 0 returns only collection, Depth: 1 includes members
members = depth == "0" ? "" : contacts.map { etag_response(it) }.join
<<~XML
@@ -409,7 +403,8 @@ module ProTacts
# at its current etag, the multiple-changes case section 3.5
# allows one response for. A member whose net is a removal
# answers as section 3.2 spells it: href and 404, no
- # propstat. #
+ # propstat.
+ #
# Depth stays unread though the section defines the report
# only at 0: macOS sends Depth: 1 (fixture 08), and 400-ing
# the one real client over a header it ignores serves the
@@ -490,8 +485,6 @@ module ProTacts
r.get String do |filename|
contact = store.contact(filename.delete_suffix(".vcf"))
- # No match falls through to the empty-body 404 that the
- # not_found handler fills in.
if contact
response["Content-Type"] = "text/vcard; charset=utf-8"
# RFC 7232 section 2.3; must match the getetag reported for
@@ -651,8 +644,6 @@ module ProTacts
# validity first, the conditionals on stored state after.
#: (untyped r, String id) -> String?
def apply_edit(r, id)
- # No match is nil, which falls through to the empty-body 404 the
- # not_found handler fills in — the GET handler's rule.
contact = store.contact(id)
return if contact.nil?
@@ -663,19 +654,12 @@ module ProTacts
last = r.params["last"].to_s.strip
return edit_screen(contact, notice: "A contact needs a name.") if first.empty? && last.empty?
- # The birthday row's parse — request validity, standing with the
- # name check rather than the stored-state conditionals below
- # (write_card's ordering rule). A POST that carries no birthday
- # group keeps the model, the phones' is-a-Hash posture — this
- # form's own save does when it rendered no birthday row, no
- # birthday held and none added from the dialog
- # (Admin::ContactsEdit), and anything else never carried one; a
- # group of three blanks is the row's blank-equals-absent, a
- # removal. The browser's number
- # inputs make garbage a hand-crafted POST's own, so the refusal
- # is the name toast's backstop sibling: the constructor's
- # ArgumentError is the grammar's own refusal, caught at the one
- # boundary with a re-render to fall back to.
+ # Request validity, standing with the name check rather than the
+ # stored-state conditionals below (write_card's ordering rule). A
+ # POST that carries no birthday group keeps the model, the phones'
+ # is-a-Hash posture — this form's own save does when it rendered
+ # no birthday row, and anything else never carried one; a group of
+ # three blanks is the row's blank-equals-absent, a removal.
birthday =
if (fields = r.params["birthday"]).is_a?(Hash)
begin
@@ -697,14 +681,10 @@ module ProTacts
# race window between check and write, noted there.
return edit_screen(contact, notice: "This contact changed since the page loaded; nothing was saved.") if r.params["etag"].to_s != contact.etag
- # A stored card carrying its own BDAY lines is the one state the
- # birthday row cannot write: the model is empty and the spelling
- # stayed in the card because no served form recomposes it
- # (Store#put's case analysis), so a birthday submitted here would
- # compose a second BDAY beside the card's own. Refused whole —
- # one submit, one etag check, one write
- # (docs/plans/2026-09-07-web-birthday-editor.md, which also
- # records the migration not taken).
+ # The one state the birthday row cannot write, refused whole:
+ # docs/plans/2026-09-07-web-birthday-editor.md, "The one hazard:
+ # a card that carries its own BDAY", which also records the
+ # migration not taken.
if birthday && contact.stored.lines.any? { it.names?("BDAY") }
return edit_screen(contact, notice: "This contact's card carries its own birthday spelling; nothing was saved.")
end
@@ -713,8 +693,6 @@ module ProTacts
r.redirect "/contacts/#{id}", 303
end
- # The re-render a refused save answers with: the edit screen again,
- # from the current card, with the refusal as its toast.
#: (Contact contact, ?notice: String) -> String
def edit_screen(contact, notice: nil)
response["Content-Type"] = "text/html; charset=utf-8"
@@ -738,15 +716,9 @@ module ProTacts
"END:VCARD\r\n"
end
- # The surgical save (docs/plans/2026-09-05-web-card-editor.md):
- # each field names the property it replaces on the stored card's
- # own bytes, and a property the form has no field for is never
- # mentioned — what is never mentioned cannot be lost. Blank equals
- # absent throughout, the reader's own rule (Contact#text_of) in the
- # other direction: a blank nickname or note removes the property,
- # and a blank name was already refused above. REV is not touched —
- # the change log is the record of when, and macOS re-stamps REV on
- # its own next rewrite.
+ # The surgical save — the hazard it exists to remove, the
+ # blank-equals-absent rule, and why REV is left alone are
+ # docs/plans/2026-09-05-web-card-editor.md.
#: (Contact contact, String first, String last, Hash[String, untyped] params) -> VCard
def edited_card(contact, first, last, params)
nickname = params["nickname"].to_s.strip
@@ -815,11 +787,7 @@ module ProTacts
card.insert(added)
end
- # The emails' half of the surgical save: the phones' own walk over
- # EMAIL — each row names its line by digest, an unchanged row is
- # skipped, a changed one swaps the value under the line's own
- # header, a blank removes the line, and the add dialog's rows land
- # as bare EMAIL lines before END:VCARD.
+ # #edited_phones' walk, over EMAIL.
#: (Contact contact, VCard card, Hash[String, untyped] params) -> VCard
def edited_emails(contact, card, params)
rows = params["email"]
@@ -847,22 +815,16 @@ module ProTacts
card.insert(added)
end
- # The addresses' half of the surgical save: the same
- # digest-addressed walk, over a row that is six fields rather
- # than one (Admin::ContactsEdit). A row unchanged throughout is
- # skipped whole — the phones' rule, keeping an untouched line's
- # bytes its own — and a changed one is rebuilt by the splice
- # below. Removal is the reader's own rule (Contact#address_of): a
- # row blank throughout, po box included, removes the line, where
- # a partially blanked one keeps it — partial blanks are legal
- # empty components.
+ # #edited_phones' walk, over a row that is six fields rather than
+ # one (Admin::ContactsEdit). Removal is the reader's own rule
+ # (Contact#address_of): a row blank throughout, po box included,
+ # removes the line, where a partially blanked one keeps it —
+ # partial blanks are legal empty components.
#: (Contact contact, VCard card, Hash[String, untyped] params) -> VCard
def edited_addresses(contact, card, params)
rows = params["address"]
if rows.is_a?(Hash)
contact.addresses.each do |address|
- # The property is nil only for a line that would not read —
- # the phones' own guard.
property = address.line.property
next if property.nil?
@@ -885,8 +847,6 @@ module ProTacts
card.insert(added.filter_map { address_line(nil, it) })
end
- # A row is unchanged when every field submits its current
- # reading — the phones' skip at the component grain.
#: (Contact::Address address, untyped submitted) -> bool
def address_unchanged?(address, submitted)
ADDRESS_COMPONENTS.keys.all? do |name|
@@ -988,14 +948,14 @@ module ProTacts
card.replace("FN", ["FN:#{VCard.escape([first, last].reject(&:empty?).join(" "))}\r\n"])
end
- # N's replacement line: a splice over the still-escaped value
- # (VCard.split_raw_components), not an unescape-then-re-escape round
- # trip, which is not byte-stable. The first two components are the
- # form's; the remaining three — additional, prefixes, suffixes (RFC
- # 2426 section 3.1.2) — rejoin byte for byte. A card with no N a
- # form can read (none, or a line that would not) splices into a
- # bare five-component value; one short of five is padded, the same
- # empties a whole-N writer would leave.
+ # N's replacement line. The first two components are the form's;
+ # the remaining three — additional, prefixes, suffixes (RFC 2426
+ # section 3.1.2) — rejoin byte for byte, which is what the splice
+ # over the still-escaped value buys
+ # (docs/plans/2026-09-05-web-card-editor.md). A card with no N a
+ # form can read splices into a bare five-component value; one
+ # short of five is padded, the same empties a whole-N writer
+ # would leave.
#: (VCard card, String first, String last) -> String
def n_line(card, first, last)
property = card.properties.find { it.name.casecmp?("N") }
@@ -1151,12 +1111,10 @@ module ProTacts
XML
end
- # An href with no match is reported as a 404 inside the 207 rather than
- # failing the request (RFC 6352 section 8.7).
- #: (String requested) -> String
# A member the collection does not answer for: the multiget miss,
- # and the removal shape a sync-collection delta reports (RFC 6578
- # section 3.2 — href and 404, no propstat).
+ # reported as a 404 inside the 207 rather than failing the request
+ # (RFC 6352 section 8.7), and the removal shape a sync-collection
+ # delta reports (RFC 6578 section 3.2 — href and 404, no propstat).
#: (String requested) -> String
def missing_response(requested)
<<~XML
diff --git a/test/pro_tacts/test_birthday.rb b/test/pro_tacts/test_birthday.rb
index 02983aa..1b0f046 100644
--- a/test/pro_tacts/test_birthday.rb
+++ b/test/pro_tacts/test_birthday.rb
@@ -155,8 +155,8 @@ class BirthdayTest < Minitest::Test
assert_equal ProTacts::Birthday.new(day: 12), ProTacts::Birthday.from_value("---12")
end
- # A bare 1604 date is a full date — the sentinel is the parameter's
- # to claim, exactly as from_property reads it.
+ # The sentinel is the parameter's to claim, exactly as from_property
+ # reads it.
def test_from_value_reads_a_bare_1604_date_as_a_full_date
assert_equal ProTacts::Birthday.new(year: 1604, month: 4, day: 12), ProTacts::Birthday.from_value("1604-04-12")
end
diff --git a/test/pro_tacts/test_contact.rb b/test/pro_tacts/test_contact.rb
index 2510f50..e1f8894 100644
--- a/test/pro_tacts/test_contact.rb
+++ b/test/pro_tacts/test_contact.rb
@@ -131,8 +131,8 @@ class ContactTest < Minitest::Test
phones.first.line.digest
end
- # A line that would not read is a row no form can address: it reads
- # as no phone, and stays in the card's lines, served from its bytes.
+ # A line that would not read is a row no form can address. It stays
+ # in the card's lines, served from its bytes.
def test_a_phone_line_that_would_not_read_is_no_phone
broken = STRUCTURED.sub("TEL;TYPE=mobile:+1-555-0100\r\n", "TEL;=;:+1-555-0100\r\n")
@@ -147,9 +147,6 @@ class ContactTest < Minitest::Test
assert_equal "home", emails.fetch(0).type
end
- # Each email carries the line it was read from, the phones' own
- # address for a save: the digest names the served card's line, which
- # is the stored one's too — composition only inserts the BDAY.
def test_every_email_carries_the_line_it_was_read_from
email = contact(STRUCTURED).emails.fetch(0)
@@ -158,8 +155,6 @@ class ContactTest < Minitest::Test
email.line.digest
end
- # A line that would not read is a row no form can address: it reads
- # as no email, and stays in the card's lines, served from its bytes.
def test_an_email_line_that_would_not_read_is_no_email
broken = STRUCTURED.sub("EMAIL;TYPE=home:ada@example.com\r\n", "EMAIL;=;:ada@example.com\r\n")
@@ -179,8 +174,6 @@ class ContactTest < Minitest::Test
assert_equal "home", address.type
end
- # The address carries its line like the single-valued shapes do —
- # the digest is the row's address in a save.
def test_every_address_carries_the_line_it_was_read_from
address = contact(STRUCTURED).addresses.fetch(0)
@@ -191,8 +184,6 @@ class ContactTest < Minitest::Test
), address.line.digest
end
- # A line that would not read is a row no form can address — no
- # address reads, and the line stays enumerable, served from its bytes.
def test_an_adr_line_that_would_not_read_is_no_address
broken = STRUCTURED.sub(
"ADR;TYPE=home:;;12 Analytical Way;London;England;NW1 1AA;United Kingdom\r\n",
@@ -245,8 +236,7 @@ class ContactTest < Minitest::Test
assert_equal birthday, contact(STRUCTURED, birthday:).birthday
end
- # The served card is the stored one with the birthday's line composed
- # in immediately before END:VCARD — the bytes a client downloads.
+ # Immediately before END:VCARD.
def test_the_served_card_composes_the_birthday_in
birthday = ProTacts::Birthday.new(year: 1985, month: 12, day: 10)
composed = STRUCTURED.sub("END:VCARD\r\n", "BDAY:1985-12-10\r\nEND:VCARD\r\n")
@@ -308,8 +298,8 @@ class ContactTest < Minitest::Test
assert_equal ProTacts::Contact.etag_for(ProTacts::VCard.new(card)), contact(card).etag
end
- # Inherited lines are card contents like any other, so the accessors
- # read them: a group's number is a phone on the member's card.
+ # Inherited lines are card contents like any other: a group's number
+ # is a phone on the member's card.
def test_the_accessors_read_inherited_lines
card = "BEGIN:VCARD\r\nVERSION:3.0\r\nFN:Aiden\r\nUID:aiden\r\nEND:VCARD\r\n"
diff --git a/test/pro_tacts/test_store.rb b/test/pro_tacts/test_store.rb
index fc12ad4..a9fad3d 100644
--- a/test/pro_tacts/test_store.rb
+++ b/test/pro_tacts/test_store.rb
@@ -105,7 +105,7 @@ class StoreTest < Minitest::Test
## UIDs
# The read behind the no-uid-conflict precondition (RFC 6352 section
- # 6.3.2.1): which card, if any, owns this UID.
+ # 6.3.2.1).
def test_the_card_holding_a_uid_is_found_by_it
with_store({"aiden" => AIDEN}) do |store|
assert_equal "aiden", store.card_id_with_uid("aiden")
@@ -118,8 +118,7 @@ class StoreTest < Minitest::Test
end
end
- # The lookup runs through the index, whose name column ignores case,
- # so a card that spelled the property lowercase is still found.
+ # The lookup runs through the index, whose name column ignores case.
def test_a_lowercase_uid_property_is_found
lowercase = "BEGIN:VCARD\r\nVERSION:3.0\r\nFN:Aiden\r\nuid:aiden\r\nEND:VCARD\r\n"
@@ -577,9 +576,8 @@ class StoreTest < Minitest::Test
end
end
- # One line the parser cannot read does not cost the card the lines
- # that read: the index is what this server understood, not an
- # all-or-nothing verdict on the card.
+ # The index is what this server understood, not an all-or-nothing
+ # verdict on the card.
def test_a_card_is_indexed_by_the_lines_that_read
unreadable = AIDEN.sub("FN:Aiden\r\n", "FN:Aiden\r\nTEL;HOME:+1-555-1234\r\n")
with_store({"aiden" => unreadable}) do |store|
@@ -658,13 +656,8 @@ class StoreTest < Minitest::Test
end
end
- # A BDAY the model cannot recompose stays in the card verbatim and
- # empties the model: the card's own line speaks for itself, and
- # compose must never add a second one beside it.
- # A BDAY the model cannot recompose stays in the card verbatim and
- # empties the model: the card's own line speaks for itself, and
- # nothing composes a second one beside it. A fold travels with its
- # line, byte for byte.
+ # The card's own line speaks for itself, and nothing composes a
+ # second one beside it. A fold travels with its line, byte for byte.
def test_an_unmodeled_bday_stays_in_the_card_and_empties_the_model
["BDAY:--0412", "BDAY:1985-\r\n 04\r\n", "BDAY:1985-04-12\r\nBDAY:1986-04-12\r\n"].each do |bday|
unmodeled = AIDEN.sub("END:VCARD\r\n", "#{bday}END:VCARD\r\n")
@@ -678,20 +671,12 @@ class StoreTest < Minitest::Test
end
end
- # The card's half of the same rule. A BDAY in a shape no client
- # renders lives in the card — the model has no spelling for it — and
- # macOS Contacts drops those lines from every card it writes, so a
- # rewrite that omits the BDAY carries them across or loses them
- # (docs/macos-contacts.md, "A birthday the client cannot render is
- # dropped from the card").
- # A BDAY sharing its line's bytes with another content line — a bare
- # CR packs two into one physical line — is a shape the parser is
- # built to assume macOS never sends, so it is never read: the line
- # stays verbatim and the model empties. The store says nothing about
- # it. A value it never read is not a value it failed to recognize,
- # and reporting it as an odd BDAY would send anyone reading the
- # message looking in the wrong place. WebTest holds the report that
- # is worth making, at the arrival.
+ # A bare CR packs two content lines into one physical line, a shape
+ # the parser is built to assume macOS never sends, so the line is
+ # never read. The store says nothing about it: a value it never read
+ # is not a value it failed to recognize, and reporting it as an odd
+ # BDAY would send anyone reading the message looking in the wrong
+ # place. WebTest holds the report worth making, at the arrival.
def test_a_bday_sharing_its_line_arrives_whole_and_unreported
shared = AIDEN.sub("END:VCARD\r\n", "BDAY:1985-04-12\rNOTE:b\r\nEND:VCARD\r\n")
@@ -705,6 +690,10 @@ class StoreTest < Minitest::Test
end
end
+ # macOS Contacts drops the lines it cannot render from every card it
+ # writes, so a rewrite that omits the BDAY carries them across rather
+ # than reading the absence as a deletion (docs/macos-contacts.md, "A
+ # birthday the client cannot render is dropped from the card").
def test_a_birthday_no_client_renders_survives_a_rewrite_that_drops_it
["BDAY:1985-04", "BDAY:1985", "BDAY:--04", "BDAY:---12"].each do |line|
with_store({"aiden" => AIDEN.sub("END:VCARD\r\n", "#{line}\r\nEND:VCARD\r\n")}) do |store|
@@ -867,7 +856,6 @@ class StoreTest < Minitest::Test
end
end
- # The limit keeps the list the length a screen wants, off the front.
def test_upcoming_birthdays_take_the_first_n
september = Date.new(2026, 9, 3)
cards = (1..3).to_h do |n|
@@ -879,8 +867,7 @@ class StoreTest < Minitest::Test
end
end
- # A birthday without a year is on the day and in the list — the age
- # is the view's question, not the query's.
+ # The age is the view's question, not the query's.
def test_a_birthday_without_a_year_is_upcoming
september = Date.new(2026, 9, 3)
@@ -893,8 +880,7 @@ class StoreTest < Minitest::Test
end
end
- # The shapes on no calendar day are nobody's to place. Planted
- # directly, because no writer produces one yet.
+ # Planted directly, because no writer produces one yet.
def test_birthdays_on_no_calendar_day_are_left_out
september = Date.new(2026, 9, 3)
diff --git a/test/pro_tacts/test_web.rb b/test/pro_tacts/test_web.rb
index 06c7649..79a74ec 100644
--- a/test/pro_tacts/test_web.rb
+++ b/test/pro_tacts/test_web.rb
@@ -259,9 +259,7 @@ class WebTest < Minitest::Test
end
end
- # If-Match on a resource that does not exist fails rather than creating
- # — the client named a representation it never saw (RFC 7232 section
- # 3.1).
+ # The client named a representation it never saw (RFC 7232 section 3.1).
def test_put_with_if_match_against_nothing_is_refused
with_contacts({}) do
put_request "new", card("new", "New"),
@@ -271,8 +269,7 @@ class WebTest < Minitest::Test
end
end
- # RFC 7232 section 3.1 allows If-Match a list of tags, and `*` for any
- # current representation.
+ # RFC 7232 section 3.1.
def test_if_match_accepts_a_list_and_a_star
with_contacts({"aiden" => "Aiden"}) do
get "/dav/addressbook/aiden.vcf"
@@ -458,7 +455,6 @@ class WebTest < Minitest::Test
end
end
- # Nothing else reports: an ordinary card arrives in silence.
def test_put_of_an_ordinary_card_is_quiet
with_contacts({}) do
put_request "new", card("new", "New"), "CONTENT_TYPE" => VCARD
@@ -757,8 +753,7 @@ class WebTest < Minitest::Test
end
end
- # An empty token is the initial sync (RFC 6578 section 3.4): every
- # member reported as changed.
+ # The initial sync, RFC 6578 section 3.4.
def test_sync_collection_with_no_token_lists_every_member
with_contacts({"aiden" => "Aiden", "znorth" => "Znorth"}) do
request "/dav/addressbook/", method: "REPORT", input: sync_collection("")
@@ -770,8 +765,7 @@ class WebTest < Minitest::Test
end
end
- # A removal answers as RFC 6578 section 3.2 spells it: href and 404,
- # no propstat — and nothing else moves.
+ # RFC 6578 section 3.2 spells a removal href and 404, no propstat.
def test_sync_collection_reports_a_removal_as_404
with_contacts({"aiden" => "Aiden", "znorth" => "Znorth"}) do |store|
request "/dav/addressbook/", method: "REPORT", input: sync_collection("http://pro-tacts/sync/2")