Skip to content

Commit

Permalink
Write more concise docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@kyouko-taiga
kyouko-taiga committed Sep 18, 2023
1 parent a46e62e commit 305736a
Showing 1 changed file with 26 additions and 30 deletions.
56 changes: 26 additions & 30 deletions Sources/IR/Emitter.swift
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,9 @@ import Utils
///
/// Other entry points may be used during IR passes (e.g., `emitDeinit`).
///
/// - Note: Unless documented otherwise, methods insert IR in `self.module` at `insertionPoint`.
/// - Note: Unless documented otherwise, the methods of `Emitter` type insert IR in `self.module`
/// at `self.insertionPoint`, anchoring new instructions at the given source range, named `site`
/// in their parameter lists.
struct Emitter {

/// The diagnostics of lowering errors.
Expand Down Expand Up @@ -834,7 +836,7 @@ struct Emitter {

}

/// Inserts IR for returning from current function, anchoring instructions to `s`.
/// Inserts IR for returning from current function, anchoring instructions at `s`.
private mutating func emitControlFlow(return s: ReturnStmt.ID) {
for f in frames.elements.reversed() {
emitDeallocs(for: f, at: ast[s].site)
Expand Down Expand Up @@ -1410,8 +1412,7 @@ struct Emitter {
insert(module.makeStore(x2, at: x1, at: syntax.site))
}

/// Writes an instance of `Hylo.Int` with value `v` to `storage`, anchoring new instruction at
/// `site`.
/// Writes an instance of `Hylo.Int` with value `v` to `storage`.
///
/// - Requires: `storage` is the address of uninitialized memory of type `Hylo.Int`.
private mutating func emitStore(int v: Int, to storage: Operand, at site: SourceRange) {
Expand All @@ -1420,8 +1421,7 @@ struct Emitter {
insert(module.makeStore(.word(v), at: x1, at: site))
}

/// Writes an instance of `Hylo.String` with value `v` to `storage`, anchoring new instruction at
/// `site`.
/// Writes an instance of `Hylo.String` with value `v` to `storage`.
///
/// - Requires: `storage` is the address of uninitialized memory of type `Hylo.String`.
private mutating func emitStore(string v: String, to storage: Operand, at site: SourceRange) {
Expand Down Expand Up @@ -2174,8 +2174,8 @@ struct Emitter {
UNIMPLEMENTED()
}

/// Returns the address of the member declared by `d`, specialized with `specialization` and
/// bound to `receiver`, inserting IR anchored at `site`.
/// Inserts IR to return the address of the member declared by `d`, bound to `receiver`, and
/// specialized by `specialization`.
private mutating func emitProperty(
boundTo receiver: Operand, declaredBy d: AnyDeclID,
specializedBy specialization: GenericArguments,
Expand All @@ -2196,8 +2196,8 @@ struct Emitter {
}
}

/// Returns the projection the property declared by `d`, specialized with `specialization` and
/// bound to `receiver`, inserting IR anchored at `site`.
/// Returns the projection the property declared by `d`, bound to `receiver`, and specialized by
/// `specialization`.
private mutating func emitComputedProperty(
boundTo receiver: Operand, declaredByBundle d: SubscriptDecl.ID,
specializedBy specialization: GenericArguments,
Expand All @@ -2217,8 +2217,8 @@ struct Emitter {
return insert(s)!
}

/// Returns the projection of the property declared by `d`, specialized with `specialization` and
/// bound to `receiver`, inserting IR anchored at `site`.
/// Returns the projection of the property declared by `d`, bound to `receiver`, and specialized
/// by `specialization`.
private mutating func emitComputedProperty(
boundTo receiver: Operand, declaredBy d: SubscriptImpl.ID,
specializedBy specialization: GenericArguments,
Expand Down Expand Up @@ -2258,8 +2258,7 @@ struct Emitter {
}
}

/// Inserts the IR to move-initialize/assign `storage` with `value`, anchoring new instructions
/// at `site`.
/// Inserts IR for move-initializing/assigning `storage` with `value`.
///
/// The type of `value` must a built-in or conform to `Movable` in `insertionScope`.
///
Expand Down Expand Up @@ -2337,7 +2336,7 @@ struct Emitter {
// MARK: Deinitialization

/// If `storage` is deinitializable in `self.insertionScope`, inserts the IR for deinitializing
/// it, anchoring new instructions at `site`. Otherwise, reports a diagnostic.
/// it. Otherwise, reports a diagnostic.

This comment has been minimized.

Sign in to view

Copy link
@dabrahams

dabrahams Dec 1, 2023

Collaborator

This comment is on this function: mutating func emitDeinit(_ storage: Operand, at site: SourceRange)

The naming of the function is appropriate, IMO, and it suggests that the function's primary purpose is to emit the deinitializer. Therefore I would suggest documentation that emphasizes that purpose instead of the possiblity that it is being used in the context of a user error when nothing will be emitted.:

  /// Inserts the IR for deinitializing `storage`, anchoring new instructions at `site`, 
  /// or reports an error if `storage` isn't deinitializable in `self.insertionScope`.

I think there's more we can do with documentation conventions to get rid of boilerplate, but IMO the several functions documented in this style would all be better changed as above.
///
/// Let `T` be the type of `storage`, `storage` is deinitializable iff `T` has a deinitializer
/// exposed to `self.insertionScope`.
Expand Down Expand Up @@ -2381,8 +2380,7 @@ struct Emitter {
}

/// If `storage` is deinitializable in `self.insertionScope`, inserts the IR for deinitializing
/// it, anchoring new instructions at `site`. Otherwise, reports a diagnostic for each part that
/// isn't deinitializable.
/// it. Otherwise, reports a diagnostic for each part that isn't deinitializable.
private mutating func emitDeinitParts(of storage: Operand, at site: SourceRange) {
let t = module.type(of: storage).ast

Expand All @@ -2396,8 +2394,8 @@ struct Emitter {
}

/// If `storage`, which stores a record, is deinitializable in `self.insertionScope`, inserts
/// the IR for deinitializing it, anchoring new instructions at `site`. Otherwise, reports a
/// diagnostic for each part that isn't deinitializable.
/// the IR for deinitializing it. Otherwise, reports a diagnostic for each part that isn't
/// deinitializable.
///
/// - Requires: the type of `storage` has a record layout.
private mutating func emitDeinitRecordParts(of storage: Operand, at site: SourceRange) {
Expand All @@ -2420,8 +2418,8 @@ struct Emitter {
}

/// If `storage`, which stores a union. is deinitializable in `self.insertionScope`, inserts
/// the IR for deinitializing it, anchoring new instructions at `site`. Otherwise, reports a
/// diagnostic for each part that isn't deinitializable.
/// the IR for deinitializing it. Otherwise, reports a diagnostic for each part that isn't
/// deinitializable.
///
/// - Requires: the type of `storage` is a union.
private mutating func emitDeinitUnionPayload(of storage: Operand, at site: SourceRange) {
Expand Down Expand Up @@ -2460,8 +2458,8 @@ struct Emitter {
}

/// If `storage`, which stores a union container holding a `payload`, is deinitializable in
/// `self.insertionScope`, inserts the IR for deinitializing it, anchoring new instructions at
/// `site`. Otherwise, reports a diagnostic for each part that isn't deinitializable.
/// `self.insertionScope`, inserts the IR for deinitializing it. Otherwise, reports a diagnostic
/// for each part that isn't deinitializable.
private mutating func emitDeinitUnionPayload(
of storage: Operand, containing payload: AnyType, at site: SourceRange
) {
Expand Down Expand Up @@ -2518,14 +2516,13 @@ struct Emitter {
return s
}

/// Inserts the IR for deallocating each allocation in the top frame of `self.frames`, anchoring
/// new instructions at `site`.
/// Inserts the IR for deallocating each allocation in the top frame of `self.frames`.
private mutating func emitDeallocTopFrame(at site: SourceRange) {
emitDeallocs(for: frames.top, at: site)
frames.top.allocs.removeAll()
}

/// Inserts the IR for deallocating each allocation in `f`, anchoring new instructions at `site`.
/// Inserts the IR for deallocating each allocation in `f`.
private mutating func emitDeallocs(for f: Frame, at site: SourceRange) {
for a in f.allocs.reversed() {
if a.mayHoldCaptures {
Expand All @@ -2536,7 +2533,7 @@ struct Emitter {
}

/// Appends the IR for computing the address of the given `subfield` of the record at
/// `recordAddress` and returns the resulting address, anchoring new instructions at `site`.
/// `recordAddress` and returns the resulting address.
mutating func emitSubfieldView(
_ recordAddress: Operand, at subfield: RecordPath, at site: SourceRange
) -> Operand {
Expand All @@ -2545,8 +2542,7 @@ struct Emitter {
return insert(s)!
}

/// Emits the IR trapping iff `predicate`, which is an object of type `i1`, anchoring new
/// instructions at `site`.
/// Emits the IR trapping iff `predicate`, which is an object of type `i1`.
private mutating func emitGuard(_ predicate: Operand, at site: SourceRange) {
let failure = appendBlock()
let success = appendBlock()
Expand All @@ -2558,7 +2554,7 @@ struct Emitter {
}

/// Emits the IR for copying the union discriminator of `container`, which is the address of
/// a union container, anchoring new instructions at `site`.
/// a union container.
private mutating func emitUnionDiscriminator(
_ container: Operand, at site: SourceRange
) -> Operand {
Expand Down

0 comments on commit 305736a

Please sign in to comment.