Represents parts of the markup that can contain strings, like inline code, code block or plain text. More...

#include <Markup.h>

Inheritance diagram for clang::clangd::markup::Paragraph:

Public Member Functions
void	renderEscapedMarkdown (llvm::raw_ostream &OS) const override
void	renderMarkdown (llvm::raw_ostream &OS) const override
void	renderPlainText (llvm::raw_ostream &OS) const override
std::unique_ptr< Block >	clone () const override
Paragraph &	appendText (llvm::StringRef Text)
	Append plain text to the end of the string.
Paragraph &	appendEmphasizedText (llvm::StringRef Text)
	Append emphasized text, this translates to the * block in markdown.
Paragraph &	appendBoldText (llvm::StringRef Text)
	Append bold text, this translates to the ** block in markdown.
bool	isHardLineBreakIndicator (llvm::StringRef Rest, bool IsMarkdown) const
	Append inline code, this translates to the ` block in markdown.
bool	isHardLineBreakAfter (llvm::StringRef Line, llvm::StringRef Rest, bool IsMarkdown) const
	Checks if a hard line break should be added after the given line.
void	renderNewlinesMarkdown (llvm::raw_ostream &OS, llvm::StringRef ParagraphText) const
	Go through the contents line by line to handle the newlines and required spacing correctly for markdown rendering.
void	addCodeBlock (std::string Code, std::string Language="cpp")
	Go through the contents line by line to handle the newlines and required spacing correctly for plain text rendering.
Paragraph &	addHeading (size_t Level)
	Heading is a special type of paragraph that will be prepended with `Level` many '#'s in markdown.
BulletList &	addBulletList ()
std::string	asEscapedMarkdown () const
	Doesn't contain any trailing newlines and escaped markdown syntax.
std::string	asMarkdown () const
	Doesn't contain any trailing newlines.
std::string	asPlainText () const
	Doesn't contain any trailing newlines.
Public Member Functions inherited from clang::clangd::markup::Block
std::string	asEscapedMarkdown () const
std::string	asMarkdown () const
std::string	asPlainText () const
virtual bool	isRuler () const
virtual	~Block ()=default

Detailed Description

Represents parts of the markup that can contain strings, like inline code, code block or plain text.

One must introduce different paragraphs to create separate blocks.

Definition at line 45 of file Markup.h.

Member Function Documentation

◆ addBulletList()

BulletList & clang::clangd::markup::Paragraph::addBulletList ( )

◆ addCodeBlock()

void clang::clangd::markup::Paragraph::addCodeBlock	(	std::string	Code,
		std::string	Language = "cpp" )

Go through the contents line by line to handle the newlines and required spacing correctly for plain text rendering.

Newlines are added if:

the line ends with 2 spaces and a newline follows
the line ends with punctuation that indicates a line break (.:,;!?)

the next line starts with a hard line break indicator (->#‘\ or a / digit followed by ’.' or ')'), ignoring leading whitespace. / / Otherwise, newlines in the input are replaced with a single space. / / Multiple spaces are collapsed into a single space. / / Lines containing only whitespace are ignored. / / This newline handling is only used when the client requests plain / text for hover/signature help content. / Therefore with this approach we mimic the behavior of markdown rendering / for these clients. / /

Parameters

OS	The stream to render to. /
ParagraphText	The text of the paragraph to render. void renderNewlinesPlaintext(llvm::raw_ostream &OS, llvm::StringRef ParagraphText) const; };

/ Represents a sequence of one or more documents. Knows how to print them in a / list like format, e.g. by prepending with "- " and indentation. class BulletList : public Block { public: BulletList(); ~BulletList();

A BulletList rendered in markdown is a tight list if it is not a nested list and no item contains multiple paragraphs. Otherwise, it is a loose list. void renderEscapedMarkdown(llvm::raw_ostream &OS) const override; void renderMarkdown(llvm::raw_ostream &OS) const override; void renderPlainText(llvm::raw_ostream &OS) const override; std::unique_ptr<Block> clone() const override;

class Document &addItem();

private: std::vector<class Document> Items; };

/ A format-agnostic representation for structured text. Allows rendering into / markdown and plaintext. class Document { public: Document() = default; Document(const Document &Other) { *this = Other; } Document &operator=(const Document &); Document(Document &&) = default; Document &operator=(Document &&) = default;

void append(Document Other);

/ Adds a semantical block that will be separate from others. Paragraph &addParagraph(); / Inserts a horizontal separator to the document. void addRuler(); / Adds a block of code. This translates to a ``` block in markdown. In plain text representation, the code block will be surrounded by newlines.

◆ addHeading()

Paragraph & clang::clangd::markup::Paragraph::addHeading ( size_t Level )

Heading is a special type of paragraph that will be prepended with Level many '#'s in markdown.

◆ appendBoldText()

Paragraph & Paragraph::appendBoldText ( llvm::StringRef Text )

Append bold text, this translates to the ** block in markdown.

Definition at line 775 of file Markup.cpp.

References clang::canonicalizeSpaces(), and clang::clangd::Text.

◆ appendEmphasizedText()

Paragraph & Paragraph::appendEmphasizedText ( llvm::StringRef Text )

Append emphasized text, this translates to the * block in markdown.

Definition at line 770 of file Markup.cpp.

References clang::canonicalizeSpaces(), and clang::clangd::Text.

◆ appendText()

Paragraph & Paragraph::appendText ( llvm::StringRef Text )

Append plain text to the end of the string.

Definition at line 761 of file Markup.cpp.

References clang::clangd::Text.

Referenced by clang::clangd::parseDocumentationParagraph().

◆ asEscapedMarkdown()

std::string clang::clangd::markup::Paragraph::asEscapedMarkdown ( ) const

Doesn't contain any trailing newlines and escaped markdown syntax.

It is expected that the result of this function is rendered as markdown.

◆ asMarkdown()

std::string clang::clangd::markup::Paragraph::asMarkdown ( ) const

Doesn't contain any trailing newlines.

It is expected that the result of this function is rendered as markdown.

◆ asPlainText()

std::string clang::clangd::markup::Paragraph::asPlainText ( ) const

Doesn't contain any trailing newlines.

◆ clone()

std::unique_ptr< Block > Paragraph::clone ( ) const

overridevirtual

Implements clang::clangd::markup::Block.

Definition at line 577 of file Markup.cpp.

◆ isHardLineBreakAfter()

bool Paragraph::isHardLineBreakAfter	(	llvm::StringRef	Line,
		llvm::StringRef	Rest,
		bool	IsMarkdown ) const

Checks if a hard line break should be added after the given line.

Definition at line 630 of file Markup.cpp.

References isHardLineBreakIndicator().

Referenced by renderNewlinesMarkdown().

◆ isHardLineBreakIndicator()

bool Paragraph::isHardLineBreakIndicator	(	llvm::StringRef	Rest,
		bool	IsMarkdown ) const

Append inline code, this translates to the ` block in markdown.

/ Preserve indicates the code span must be apparent even in plaintext. Paragraph &appendCode(llvm::StringRef Code, bool Preserve = false);

/ Ensure there is space between the surrounding chunks. / Has no effect at the beginning or end of a paragraph. Paragraph &appendSpace();

private: enum ChunkKind { PlainText, InlineCode, Bold, Emphasized }; struct Chunk { ChunkKind Kind = PlainText; Preserve chunk markers in plaintext. bool Preserve = false; std::string Contents; Whether this chunk should be surrounded by whitespace. Consecutive SpaceAfter and SpaceBefore will be collapsed into one space. Code spans don't usually set this: their spaces belong "inside" the span. bool SpaceBefore = false; bool SpaceAfter = false; }; std::vector<Chunk> Chunks;

/ Estimated size of the string representation of this paragraph. / Used to reserve space in the output string. / Each time paragraph content is added, this value is updated. / This is an estimate, so it may not be accurate but can help / reducing dynamically reallocating string memory. unsigned EstimatedStringSize = 0;

Paragraph &appendChunk(llvm::StringRef Contents, ChunkKind K);

llvm::StringRef chooseMarker(llvm::ArrayRef<llvm::StringRef> Options, llvm::StringRef Text) const;

/ Checks if the given line ends with punctuation that indicates a line break / (.:,;!?). / / If IsMarkdown is false, lines ending with 2 spaces are also considered / as indicating a line break. This is not needed for markdown because the / client renderer will handle this case. bool punctuationIndicatesLineBreak(llvm::StringRef Line, bool IsMarkdown) const;

/ Checks if the given line starts with a hard line break indicator. / / If IsMarkdown is true, only '@' and '\' are considered as indicators. / Otherwise, '-', '*', '@', '\', '>', '#', '‘’ and a digit followed by '.' or ')' are also considered as indicators.

Definition at line 601 of file Markup.cpp.

Referenced by isHardLineBreakAfter().

◆ renderEscapedMarkdown()

void Paragraph::renderEscapedMarkdown ( llvm::raw_ostream & OS ) const

overridevirtual

Implements clang::clangd::markup::Block.

Definition at line 501 of file Markup.cpp.

References renderNewlinesMarkdown().

◆ renderMarkdown()

void Paragraph::renderMarkdown ( llvm::raw_ostream & OS ) const

overridevirtual

Implements clang::clangd::markup::Block.

Definition at line 537 of file Markup.cpp.

References renderNewlinesMarkdown().

◆ renderNewlinesMarkdown()

void Paragraph::renderNewlinesMarkdown	(	llvm::raw_ostream &	OS,
		llvm::StringRef	ParagraphText ) const

Go through the contents line by line to handle the newlines and required spacing correctly for markdown rendering.

Newlines are added if:

the line ends with punctuation that indicates a line break (.:,;!?)
the next line starts with a hard line break indicator \ (escaped markdown/doxygen command) or @ (doxygen command)

This newline handling is only used when the client requests markdown for hover/signature help content. Markdown does not add any newlines inside paragraphs unless the user explicitly adds them. For hover/signature help content, we still want to add newlines in some cases to improve readability, especially when doxygen parsing is disabled or not implemented (like for signature help). Therefore we add newlines in the above mentioned cases.

In addition to that, we need to consider that the user can configure clangd to treat documentation comments as plain text, while the client requests markdown. In this case, all markdown syntax is escaped and will not be rendered as expected by markdown. Examples are lists starting with '-' or headings starting with '#'. With the above next line heuristics, these cases are also covered by the '\' new line indicator.

FIXME: The heuristic fails e.g. for lists starting with '*' because it is also used for emphasis in markdown and should not be treated as a newline.

Parameters

OS	The stream to render to.
ParagraphText	The text of the paragraph to render.

Definition at line 478 of file Markup.cpp.

References isHardLineBreakAfter().

Referenced by renderEscapedMarkdown(), and renderMarkdown().

◆ renderPlainText()

void Paragraph::renderPlainText ( llvm::raw_ostream & OS ) const

overridevirtual

Implements clang::clangd::markup::Block.

Definition at line 672 of file Markup.cpp.

The documentation for this class was generated from the following files:

Public Member Functions

Detailed Description

Member Function Documentation

◆ addBulletList()

◆ addCodeBlock()

◆ addHeading()

◆ appendBoldText()

◆ appendEmphasizedText()

◆ appendText()

◆ asEscapedMarkdown()

◆ asMarkdown()

◆ asPlainText()

◆ clone()

◆ isHardLineBreakAfter()

◆ isHardLineBreakIndicator()

◆ renderEscapedMarkdown()

◆ renderMarkdown()

◆ renderNewlinesMarkdown()

◆ renderPlainText()