BaseDoc.php 4.34 KB
Newer Older
1
<?php
2 3 4 5 6
/**
 * @link http://www.yiiframework.com/
 * @copyright Copyright (c) 2008 Yii Software LLC
 * @license http://www.yiiframework.com/license/
 */
7

8
namespace yii\apidoc\models;
9

10 11
use phpDocumentor\Reflection\DocBlock\Tag\DeprecatedTag;
use phpDocumentor\Reflection\DocBlock\Tag\SinceTag;
12
use yii\base\Object;
13
use yii\helpers\StringHelper;
14

15
/**
16
 * Base class for API documentation information.
17 18 19 20
 *
 * @author Carsten Brandt <mail@cebe.cc>
 * @since 2.0
 */
21 22
class BaseDoc extends Object
{
23 24 25 26
    /**
     * @var \phpDocumentor\Reflection\DocBlock\Context
     */
    public $phpDocContext;
27

28
    public $name;
29

30 31 32
    public $sourceFile;
    public $startLine;
    public $endLine;
33

34 35 36 37 38
    public $shortDescription;
    public $description;
    public $since;
    public $deprecatedSince;
    public $deprecatedReason;
39

40 41 42 43
    /**
     * @var \phpDocumentor\Reflection\DocBlock\Tag[]
     */
    public $tags = [];
44

45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64
    public function hasTag($name)
    {
        foreach ($this->tags as $tag) {
            if (strtolower($tag->getName()) == $name) {
                return true;
            }
        }
        return false;
    }

    public function removeTag($name)
    {
        foreach ($this->tags as $i => $tag) {
            if (strtolower($tag->getName()) == $name) {
                unset($this->tags[$i]);
            }
        }
    }


65 66
    /**
     * @param \phpDocumentor\Reflection\BaseReflector $reflector
67 68
     * @param Context $context
     * @param array $config
69 70 71 72
     */
    public function __construct($reflector = null, $context = null, $config = [])
    {
        parent::__construct($config);
73

74 75 76
        if ($reflector === null) {
            return;
        }
77

78 79 80 81
        // base properties
        $this->name = ltrim($reflector->getName(), '\\');
        $this->startLine = $reflector->getNode()->getAttribute('startLine');
        $this->endLine = $reflector->getNode()->getAttribute('endLine');
82

83 84 85
        $docblock = $reflector->getDocBlock();
        if ($docblock !== null) {
            $this->shortDescription = ucfirst($docblock->getShortDescription());
86
            if (empty($this->shortDescription) && !($this instanceof PropertyDoc) && $context !== null && $docblock->getTagsByName('inheritdoc') === null) {
87 88 89 90 91 92
                $context->errors[] = [
                    'line' => $this->startLine,
                    'file' => $this->sourceFile,
                    'message' => "No short description for " . substr(StringHelper::basename(get_class($this)), 0, -3) . " '{$this->name}'",
                ];
            }
93
            $this->description = $docblock->getLongDescription()->getContents();
94

95
            $this->phpDocContext = $docblock->getContext();
96

97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115
            $this->tags = $docblock->getTags();
            foreach ($this->tags as $i => $tag) {
                if ($tag instanceof SinceTag) {
                    $this->since = $tag->getVersion();
                    unset($this->tags[$i]);
                } elseif ($tag instanceof DeprecatedTag) {
                    $this->deprecatedSince = $tag->getVersion();
                    $this->deprecatedReason = $tag->getDescription();
                    unset($this->tags[$i]);
                }
            }
        } elseif ($context !== null) {
            $context->errors[] = [
                'line' => $this->startLine,
                'file' => $this->sourceFile,
                'message' => "No docblock for element '{$this->name}'",
            ];
        }
    }
116

117
    // TODO implement
Carsten Brandt committed
118 119 120 121 122 123 124 125 126 127 128 129
//	public function loadSource($reflection)
//	{
//		$this->sourceFile;
//		$this->startLine;
//		$this->endLine;
//	}
//
//	public function getSourceCode()
//	{
//		$lines = file(YII_PATH . $this->sourcePath);
//		return implode("", array_slice($lines, $this->startLine - 1, $this->endLine - $this->startLine + 1));
//	}
130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145

    public static function extractFirstSentence($text)
    {
        if (mb_strlen($text) > 4 && ($pos = mb_strpos($text, '.', 4, 'utf-8')) !== false) {
            $sentence = mb_substr($text, 0, $pos + 1, 'utf-8');
            if (mb_strlen($text) >= $pos + 3) {
                $abbrev = mb_substr($text, $pos - 1, 4);
                if ($abbrev === 'e.g.' || $abbrev === 'i.e.') { // do not break sentence after abbreviation
                    $sentence .= static::extractFirstSentence(mb_substr($text, $pos + 1));
                }
            }
            return $sentence;
        } else {
            return $text;
        }
    }
Luciano Baraglia committed
146
}