Mirrors/servo
1
0
Fork 0
mirror of https://github.com/servo/servo.git synced 2025-08-04 05:00:08 +01:00
Code Issues Projects Releases Packages Wiki Activity

Layout 2020: Fix issues with float implementation documentation

Browse source 
Fix some rustdoc comments which won't process properly unless they start
with three '/' characters. In addition, improve the name of a function
and add some missing documentation.
This commit is contained in:
Martin Robinson 2023-06-14 17:09:56 +02:00
parent f8235ab3fb
commit 3b3dc4adbe
No known key found for this signature in database
GPG key ID: D56AA4FA55EFE6F8
2 changed files with 64 additions and 60 deletions
Download patch file Download diff file Expand all files Collapse all files

117
components/layout_2020/flow/float.rs
View file

@ -320,7 +320,7 @@ impl ClearSide {
} }
impl FloatBand { impl FloatBand {
// Determines whether an object fits in a band. /// Determines whether an object fits in a band. Returns true if the object fits.
fn object_fits(&self, object: &PlacementInfo, walls: &ContainingBlockPositionInfo) -> bool { fn object_fits(&self, object: &PlacementInfo, walls: &ContainingBlockPositionInfo) -> bool {
match object.side { match object.side {
FloatSide::Left => { FloatSide::Left => {
@ -549,8 +549,8 @@ impl FloatBandLink {
Some(this.band.clone()) Some(this.band.clone())
} }
// Inserts a new band into the tree. If the band has the same level as a pre-existing one, /// Inserts a new band into the tree. If the band has the same level as a pre-existing one,
// replaces the existing band with the new one. /// replaces the existing band with the new one.
fn insert(&self, band: FloatBand) -> FloatBandLink { fn insert(&self, band: FloatBand) -> FloatBandLink {
let mut this = match self.0 { let mut this = match self.0 {
None => return FloatBandLink(Some(Arc::new(FloatBandNode::new(band)))), None => return FloatBandLink(Some(Arc::new(FloatBandNode::new(band)))),
@ -570,13 +570,13 @@ impl FloatBandLink {
FloatBandLink(Some(Arc::new(this))) FloatBandLink(Some(Arc::new(this)))
} }
// Corrects tree balance: /// Corrects tree balance:
// ///
// T L /// T L
// / \ / \ /// / \ / \
// L R → A T if level(T) = level(L) /// L R → A T if level(T) = level(L)
// / \ / \ /// / \ / \
// A B B R /// A B B R
fn skew(&self) -> FloatBandLink { fn skew(&self) -> FloatBandLink {
if let Some(ref this) = self.0 { if let Some(ref this) = self.0 {
if let Some(ref left) = this.left.0 { if let Some(ref left) = this.left.0 {
@ -599,13 +599,13 @@ impl FloatBandLink {
(*self).clone() (*self).clone()
} }
// Corrects tree balance: /// Corrects tree balance:
// ///
// T R /// T R
// / \ / \ /// / \ / \
// A R → T X if level(T) = level(X) /// A R → T X if level(T) = level(X)
// / \ / \ /// / \ / \
// B X A B /// B X A B
fn split(&self) -> FloatBandLink { fn split(&self) -> FloatBandLink {
if let Some(ref this) = self.0 { if let Some(ref this) = self.0 {
if let Some(ref right) = this.right.0 { if let Some(ref right) = this.right.0 {
@ -637,8 +637,6 @@ impl Debug for FloatFragment {
} }
} }
// Float boxes
impl FloatBox { impl FloatBox {
/// Creates a new float box. /// Creates a new float box.
pub fn construct<'dom>( pub fn construct<'dom>(
@ -659,6 +657,9 @@ impl FloatBox {
} }
} }
/// Lay out this float box and its children. Note that the position will be relative to
/// the float containing block formatting context. A later step adjusts the position
/// to be relative to the containing block.
pub fn layout( pub fn layout(
&mut self, &mut self,
layout_context: &LayoutContext, layout_context: &LayoutContext,
@ -799,35 +800,33 @@ impl FloatBox {
} }
} }
// Float fragment storage /// Layout state that we maintain when doing sequential traversals of the box tree in document
/// order.
// Layout state that we maintain when doing sequential traversals of the box tree in document ///
// order. /// This data is only needed for float placement and float interaction, and as such is only present
// /// if the current block formatting context contains floats.
// This data is only needed for float placement and float interaction, and as such is only present ///
// if the current block formatting context contains floats. /// All coordinates here are relative to the start of the nearest ancestor block formatting context.
// ///
// All coordinates here are relative to the start of the nearest ancestor block formatting context. /// This structure is expected to be cheap to clone, in order to allow for "snapshots" that enable
// /// restarting layout at any point in the tree.
// This structure is expected to be cheap to clone, in order to allow for "snapshots" that enable
// restarting layout at any point in the tree.
#[derive(Clone)] #[derive(Clone)]
pub(crate) struct SequentialLayoutState { pub(crate) struct SequentialLayoutState {
// Holds all floats in this block formatting context. /// Holds all floats in this block formatting context.
pub(crate) floats: FloatContext, pub(crate) floats: FloatContext,
// The (logically) bottom border edge or top padding edge of the last in-flow block. Floats /// The (logically) bottom border edge or top padding edge of the last in-flow block. Floats
// cannot be placed above this line. /// cannot be placed above this line.
// ///
// This is often, but not always, the same as the float ceiling. The float ceiling can be lower /// This is often, but not always, the same as the float ceiling. The float ceiling can be lower
// than this value because this value is calculated based on in-flow boxes only, while /// than this value because this value is calculated based on in-flow boxes only, while
// out-of-flow floats can affect the ceiling as well (see CSS 2.1 § 9.5.1 rule 6). /// out-of-flow floats can affect the ceiling as well (see CSS 2.1 § 9.5.1 rule 6).
pub(crate) bfc_relative_block_position: Length, pub(crate) bfc_relative_block_position: Length,
// Any collapsible margins that we've encountered after `bfc_relative_block_position`. /// Any collapsible margins that we've encountered after `bfc_relative_block_position`.
pub(crate) current_margin: CollapsedMargin, pub(crate) current_margin: CollapsedMargin,
} }
impl SequentialLayoutState { impl SequentialLayoutState {
// Creates a new empty `SequentialLayoutState`. /// Creates a new empty `SequentialLayoutState`.
pub(crate) fn new() -> SequentialLayoutState { pub(crate) fn new() -> SequentialLayoutState {
SequentialLayoutState { SequentialLayoutState {
floats: FloatContext::new(), floats: FloatContext::new(),
@ -836,41 +835,45 @@ impl SequentialLayoutState {
} }
} }
// Moves the current block position (logically) down by `block_distance`. /// Moves the current block position (logically) down by `block_distance`.
// ///
// Floats may not be placed higher than the current block position. /// Floats may not be placed higher than the current block position.
pub(crate) fn advance_block_position(&mut self, block_distance: Length) { pub(crate) fn advance_block_position(&mut self, block_distance: Length) {
self.bfc_relative_block_position += block_distance; self.bfc_relative_block_position += block_distance;
self.floats.lower_ceiling(self.bfc_relative_block_position); self.floats.lower_ceiling(self.bfc_relative_block_position);
} }
pub(crate) fn update_all_containing_block_offsets( /// Replace the entire [ContainingBlockPositionInfo] data structure stored
/// by this [SequentialLayoutState]. Return the old data structure.
pub(crate) fn replace_containing_block_position_info(
&mut self, &mut self,
mut new_distance: ContainingBlockPositionInfo, mut position_info: ContainingBlockPositionInfo,
) -> ContainingBlockPositionInfo { ) -> ContainingBlockPositionInfo {
mem::swap(&mut new_distance, &mut self.floats.containing_block_info); mem::swap(&mut position_info, &mut self.floats.containing_block_info);
new_distance position_info
} }
/// Return the current block position in the float containing block formatting
/// context and any uncollapsed block margins.
pub(crate) fn current_block_position_including_margins(&self) -> Length { pub(crate) fn current_block_position_including_margins(&self) -> Length {
self.bfc_relative_block_position + self.current_margin.solve() self.bfc_relative_block_position + self.current_margin.solve()
} }
// Collapses margins, moving the block position down by the collapsed value of `current_margin` /// Collapses margins, moving the block position down by the collapsed value of `current_margin`
// and resetting `current_margin` to zero. /// and resetting `current_margin` to zero.
// ///
// Call this method before laying out children when it is known that the start margin of the /// Call this method before laying out children when it is known that the start margin of the
// current fragment can't collapse with the margins of any of its children. /// current fragment can't collapse with the margins of any of its children.
pub(crate) fn collapse_margins(&mut self) { pub(crate) fn collapse_margins(&mut self) {
self.advance_block_position(self.current_margin.solve()); self.advance_block_position(self.current_margin.solve());
self.current_margin = CollapsedMargin::zero(); self.current_margin = CollapsedMargin::zero();
} }
// Returns the amount of clearance that a block with the given `clear` value at the current /// Returns the amount of clearance that a block with the given `clear` value at the current
// `bfc_relative_block_position` (with top margin included in `current_margin` if applicable) /// `bfc_relative_block_position` (with top margin included in `current_margin` if applicable)
// needs to have. /// needs to have.
// ///
// https://www.w3.org/TR/2011/REC-CSS2-20110607/visuren.html#flow-control /// https://www.w3.org/TR/2011/REC-CSS2-20110607/visuren.html#flow-control
pub(crate) fn calculate_clearance(&self, clear_side: ClearSide) -> Length { pub(crate) fn calculate_clearance(&self, clear_side: ClearSide) -> Length {
if clear_side == ClearSide::None { if clear_side == ClearSide::None {
return Length::zero(); return Length::zero();

7
components/layout_2020/flow/mod.rs
View file

@ -523,8 +523,9 @@ fn layout_in_flow_non_replaced_block_level(
inline_start, inline_start,
inline_end: inline_start + inline_size, inline_end: inline_start + inline_size,
}; };
parent_containing_block_position_info = parent_containing_block_position_info = Some(
Some(sequential_layout_state.update_all_containing_block_offsets(new_cb_offsets)); sequential_layout_state.replace_containing_block_position_info(new_cb_offsets),
);
}, },
}; };
@ -595,7 +596,7 @@ fn layout_in_flow_non_replaced_block_level(
// Now that we're done laying out our children, we can restore the // Now that we're done laying out our children, we can restore the
// parent's containing block position information. // parent's containing block position information.
sequential_layout_state sequential_layout_state
.update_all_containing_block_offsets(parent_containing_block_position_info.unwrap()); .replace_containing_block_position_info(parent_containing_block_position_info.unwrap());
// Account for padding and border. We also might have to readjust the // Account for padding and border. We also might have to readjust the
// `bfc_relative_block_position` if it was different from the content size (i.e. was // `bfc_relative_block_position` if it was different from the content size (i.e. was