phpdoc-parser 0.23.0

Structural PHPDoc parser. Parses doc-comment blocks into a tag/prose AST with accurate spans; tag bodies exposed as raw text.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70

use crate::Span;
#[cfg(feature = "serde")]
use serde::Serialize;

// =============================================================================
// Document-structure AST
// =============================================================================

/// An inline `{@tagname body}` tag embedded in text.
#[derive(Debug, Clone)]
#[cfg_attr(feature = "serde", derive(Serialize))]
pub struct InlineTag {
    /// Tag name without braces or `@`.
    pub name: String,
    /// Text after the name, if any.
    pub body: Option<String>,
    /// Source range of the whole tag.
    pub span: Span,
}

/// A segment of prose text — either plain text or an inline tag.
#[derive(Debug, Clone)]
#[cfg_attr(feature = "serde", derive(Serialize))]
#[non_exhaustive]
pub enum TextSegment {
    /// Literal prose.
    Text(String),
    /// Embedded `{@tag}`.
    InlineTag(InlineTag),
}

/// A prose run (summary, description, or tag body) that may contain inline tags.
#[derive(Debug, Clone)]
#[cfg_attr(feature = "serde", derive(Serialize))]
pub struct PhpDocText {
    /// Segments in source order.
    pub segments: Vec<TextSegment>,
    /// Source range of the text.
    pub span: Span,
}

/// A block-level `@tag` — generic, no semantic interpretation.
#[derive(Debug, Clone)]
#[cfg_attr(feature = "serde", derive(Serialize))]
pub struct PhpDocTag {
    /// Raw tag name, e.g. `"param"`, `"psalm-type"`, `"return"`.
    pub name: String,
    /// Tag body, if any.
    pub body: Option<PhpDocText>,
    /// Source range of the tag.
    pub span: Span,
}

// =============================================================================
// Top-level document
// =============================================================================

/// A parsed docblock.
#[derive(Debug, Clone)]
#[cfg_attr(feature = "serde", derive(Serialize))]
pub struct PhpDoc {
    /// Leading summary text.
    pub summary: Option<PhpDocText>,
    /// Description following the summary.
    pub description: Option<PhpDocText>,
    /// Block-level tags in source order.
    pub tags: Vec<PhpDocTag>,
    /// Always `Span::new(0, text.len() as u32)`.
    pub span: Span,
}