Page Menu
Home
Phorge
Search
Configure Global Search
Log In
Files
F2890791
PhutilDocblockParser.php
No One
Temporary
Actions
Download File
Edit File
Delete File
View Transforms
Subscribe
Award Token
Flag For Later
Advanced/Developer...
View Handle
View Hovercard
Size
4 KB
Referenced Files
None
Subscribers
None
PhutilDocblockParser.php
View Options
<?php
/**
* Parse a docblock comment from source code into raw text documentation and
* metadata (like "@author" and "@return").
*/
final
class
PhutilDocblockParser
extends
Phobject
{
public
function
extractDocblocks
(
$text
)
{
$blocks
=
array
(
)
;
$matches
=
null
;
$match
=
preg_match_all
(
'@(/\*\*.*?\*/)@s'
,
$text
,
$matches
,
PREG_OFFSET_CAPTURE
|
PREG_PATTERN_ORDER
)
;
if
(
!
$match
)
{
return
$blocks
;
}
// Build a map of character offset -> line number.
$map
=
array
(
)
;
$lines
=
explode
(
"\n"
,
$text
)
;
$num
=
1
;
foreach
(
$lines
as
$line
)
{
$len
=
strlen
(
$line
)
+
1
;
for
(
$jj
=
0
;
$jj
<
$len
;
$jj
++
)
{
$map
[
]
=
$num
;
}
++
$num
;
}
foreach
(
$matches
[
0
]
as
$match
)
{
list
(
$data
,
$offset
)
=
$match
;
$blocks
[
]
=
array
(
$data
,
$map
[
$offset
]
)
;
}
return
$blocks
;
}
public
function
parse
(
$docblock
)
{
// Strip off comments.
$docblock
=
trim
(
$docblock
)
;
$docblock
=
preg_replace
(
'@^/\*\*@'
,
''
,
$docblock
)
;
$docblock
=
preg_replace
(
'@\*/$@'
,
''
,
$docblock
)
;
$docblock
=
preg_replace
(
'@^\s*\*@m'
,
''
,
$docblock
)
;
// Normalize multi-line @specials.
$lines
=
explode
(
"\n"
,
$docblock
)
;
$last
=
false
;
foreach
(
$lines
as
$k
=>
$line
)
{
// NOTE: We allow "@specials" to be preceded by up to two whitespace
// characters; more than that and we assume the block is a code block.
// Broadly, there's ambiguity between a special like:
//
// <... lots of indentation ...> @author alincoln
//
// ...and a code block like:
//
// <... lots of indentation ...> @def square(x, y):
//
// Because standard practice is to indent the entire block one level,
// we allow that and one additional space before assuming something is
// a code block.
if
(
preg_match
(
'/^\s{0,2}@\w/i'
,
$line
)
)
{
$last
=
$k
;
$lines
[
$last
]
=
trim
(
$line
)
;
}
else
if
(
preg_match
(
'/^\s*$/'
,
$line
)
)
{
$last
=
false
;
}
else
if
(
$last
!==
false
)
{
$lines
[
$last
]
=
$lines
[
$last
]
.
' '
.
trim
(
$line
)
;
unset
(
$lines
[
$k
]
)
;
}
}
$docblock
=
implode
(
"\n"
,
$lines
)
;
$special
=
array
(
)
;
// Parse @specials.
$matches
=
null
;
$have_specials
=
preg_match_all
(
'/^@([\w-]+)[ \t]*([^\n]*)/m'
,
$docblock
,
$matches
,
PREG_SET_ORDER
)
;
if
(
$have_specials
)
{
$docblock
=
preg_replace
(
'/^@([\w-]+)[ \t]*([^\n]*)?\n*/m'
,
''
,
$docblock
)
;
foreach
(
$matches
as
$match
)
{
list
(
$_
,
$type
,
$data
)
=
$match
;
$data
=
trim
(
$data
)
;
// For flags like "@stable" which don't have any string data, set the
// value to true.
if
(
!
strlen
(
$data
)
)
{
$data
=
true
;
}
if
(
!
isset
(
$special
[
$type
]
)
)
{
$special
[
$type
]
=
$data
;
}
else
{
if
(
!
is_array
(
$special
[
$type
]
)
)
{
$special
[
$type
]
=
(array)
$special
[
$type
]
;
}
$special
[
$type
]
[
]
=
$data
;
}
}
}
// Convert `array(true, true, true)` to `true`.
foreach
(
$special
as
$type
=>
$data
)
{
if
(
is_array
(
$data
)
)
{
$all_trues
=
true
;
foreach
(
$data
as
$value
)
{
if
(
$value
!==
true
)
{
$all_trues
=
false
;
break
;
}
}
if
(
$all_trues
)
{
$special
[
$type
]
=
true
;
}
}
}
$docblock
=
str_replace
(
"\t"
,
' '
,
$docblock
)
;
// Smush the whole docblock to the left edge.
$min_indent
=
80
;
$indent
=
0
;
foreach
(
array_filter
(
explode
(
"\n"
,
$docblock
)
)
as
$line
)
{
for
(
$ii
=
0
;
$ii
<
strlen
(
$line
)
;
$ii
++
)
{
if
(
$line
[
$ii
]
!=
' '
)
{
break
;
}
$indent
++
;
}
$min_indent
=
min
(
$indent
,
$min_indent
)
;
}
$docblock
=
preg_replace
(
'/^'
.
str_repeat
(
' '
,
$min_indent
)
.
'/m'
,
''
,
$docblock
)
;
$docblock
=
rtrim
(
$docblock
)
;
// Trim any empty lines off the front, but leave the indent level if there
// is one.
$docblock
=
preg_replace
(
'/^\s*\n/'
,
''
,
$docblock
)
;
return
array
(
$docblock
,
$special
)
;
}
}
File Metadata
Details
Attached
Mime Type
text/x-php
Expires
Sun, Jan 19, 14:07 (3 w, 2 d ago)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
1113403
Default Alt Text
PhutilDocblockParser.php (4 KB)
Attached To
Mode
rARC Arcanist
Attached
Detach File
Event Timeline
Log In to Comment