Codechange: move documentation to super class and add missing documentation

src/gfx_layout.cpp

@@ -217,6 +217,8 @@ Dimension Layouter::GetBounds()
 
 /**
  * Test whether a character is a non-printable formatting code
+ * @param ch The character to test.
+ * @return \c true iff it is a non-printable formatting code.
  */
 static bool IsConsumedFormattingCode(char32_t ch)
 {
@@ -340,6 +342,9 @@ ptrdiff_t Layouter::GetCharAtPosition(int x, size_t line_index) const
 
 /**
  * Get a static font instance.
+ * @param size The size of font.
+ * @param colour The font's colour.
+ * @return The cached font.
  */
 Font *Layouter::GetFont(FontSize size, TextColour colour)
 {

src/gfx_layout.h

@@ -121,7 +121,10 @@ public:
 
 		constexpr inline Position(int16_t left, int16_t right, int16_t top) : left(left), right(right), top(top) { }
 
-		/** Conversion from a single point to a Position. */
+		/**
+		 * Conversion from a single point to a Position.
+		 * @param pt The point to create the position for.
+		 */
 		constexpr inline Position(const Point &pt) : left(pt.x), right(pt.x), top(pt.y) { }
 	};
 
@@ -129,11 +132,41 @@ public:
 	class VisualRun {
 	public:
 		virtual ~VisualRun() = default;
+
+		/**
+		 * Get the font.
+		 * @return The font used for this run.
+		 */
 		virtual const Font *GetFont() const = 0;
+
+		/**
+		 * Get the number of glyphs.
+		 * @return The number of glyphs for this run.
+		 */
 		virtual int GetGlyphCount() const = 0;
+
+		/**
+		 * Get the glyphs to draw.
+		 * @return The glyphs.
+		 */
 		virtual std::span<const GlyphID> GetGlyphs() const = 0;
+
+		/**
+		 * Get the positions for each of the glyphs.
+		 * @return The glyph positions.
+		 */
 		virtual std::span<const Position> GetPositions() const = 0;
+
+		/**
+		 * Get the font leading, or distance between the baselines of consecutive lines.
+		 * @return The leading in pixels.
+		 */
 		virtual int GetLeading() const = 0;
+
+		/**
+		 * The offset for each of the glyphs to the character run that was passed to the #Layouter.
+		 * @return The offsets.
+		 */
 		virtual std::span<const int> GetGlyphToCharMap() const = 0;
 	};
 
@@ -141,14 +174,51 @@ public:
 	class Line {
 	public:
 		virtual ~Line() = default;
+
+		/**
+		 * Get the font leading, or distance between the baselines of consecutive lines.
+		 * @return The leading in pixels, which is generally the maximum of all runs..
+		 */
 		virtual int GetLeading() const = 0;
+
+		/**
+		 * Get the width of this line.
+		 * @return The width of the line.
+		 */
 		virtual int GetWidth() const = 0;
+
+		/**
+		 * Get the number of runs in this line.
+		 * @return The number of runs.
+		 */
 		virtual int CountRuns() const = 0;
+
+		/**
+		 * Get a reference to the given run.
+		 * @param run The index into the runs.
+		 * @return The reference to the run.
+		 */
 		virtual const VisualRun &GetVisualRun(int run) const = 0;
+
+		/**
+		 * Get the number of elements the given character occupies in the underlying text buffer of the Layouter.
+		 * Many use UTF-16 internally, meaning a character larger than MAX_UINT16 occupies two places in its buffer.
+		 * @param c The character to get the length for.
+		 * @return The length.
+		 */
 		virtual int GetInternalCharLength(char32_t c) const = 0;
 	};
 
+	/**
+	 * Reset the position to the start of the paragraph.
+	 */
 	virtual void Reflow() = 0;
+
+	/**
+	 * Construct a new line with a maximum width.
+	 * @param max_width The maximum width of the string.
+	 * @return A Line, or \c nullptr when at the end of the paragraph.
+	 */
 	virtual std::unique_ptr<const Line> NextLine(int max_width) = 0;
 };
 

src/gfx_layout_fallback.cpp

@@ -134,10 +134,6 @@ FallbackParagraphLayout::FallbackVisualRun::FallbackVisualRun(Font *font, const
 	}
 }
 
-/**
- * Get the height of the line.
- * @return The maximum height of the line.
- */
 int FallbackParagraphLayout::FallbackLine::GetLeading() const
 {
 	int leading = 0;
@@ -148,10 +144,6 @@ int FallbackParagraphLayout::FallbackLine::GetLeading() const
 	return leading;
 }
 
-/**
- * Get the width of this line.
- * @return The width of the line.
- */
 int FallbackParagraphLayout::FallbackLine::GetWidth() const
 {
 	if (this->empty()) return 0;
@@ -167,19 +159,11 @@ int FallbackParagraphLayout::FallbackLine::GetWidth() const
 	return positions.back().right + 1;
 }
 
-/**
- * Get the number of runs in this line.
- * @return The number of runs.
- */
 int FallbackParagraphLayout::FallbackLine::CountRuns() const
 {
-	return (uint)this->size();
+	return static_cast<int>(this->size());
 }
 
-/**
- * Get a specific visual run.
- * @return The visual run.
- */
 const ParagraphLayouter::VisualRun &FallbackParagraphLayout::FallbackLine::GetVisualRun(int run) const
 {
 	return this->at(run);
@@ -196,19 +180,11 @@ FallbackParagraphLayout::FallbackParagraphLayout(char32_t *buffer, [[maybe_unuse
 	assert(runs.rbegin()->first == length);
 }
 
-/**
- * Reset the position to the start of the paragraph.
- */
 void FallbackParagraphLayout::Reflow()
 {
 	this->buffer = this->buffer_begin;
 }
 
-/**
- * Construct a new line with a maximum width.
- * @param max_width The maximum width of the string.
- * @return A Line, or nullptr when at the end of the paragraph.
- */
 std::unique_ptr<const ParagraphLayouter::Line> FallbackParagraphLayout::NextLine(int max_width)
 {
 	/* Simple idea: