-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathdocumenting_your_code.html
85 lines (75 loc) · 8.33 KB
/
documenting_your_code.html
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
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Welcome file</title>
<link rel="stylesheet" href="https://stackedit.io/style.css" />
</head>
<body class="stackedit">
<div class="stackedit__left">
<div class="stackedit__toc">
<ul>
<li><a href="#кодты-документтегіздеу">Кодты документтегіздеу</a>
<ul>
<li><a href="#phpdoc">PHPDoc</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div class="stackedit__right">
<div class="stackedit__html">
<h1 id="кодты-документтегіздеу">Кодты документтегіздеу</h1>
<h2 id="phpdoc">PHPDoc</h2>
<p>PHPDoc PHP кодын түсініктемелу әдісіді айту үшін пайдаланылатын ішкі стандарт. <a href="https://docs.phpdoc.org/latest/guide/references/phpdoc/tags/index.html">тегтердің</a> жатты мәні мен мисалдар тізімін PHPDoc құжатында таба аласыз.</p>
<p>Төменде бір сыныпты жеке өрістерімен документтегіздеу міндеттілігін көрейік;</p>
<pre class=" language-php"><code class="prism language-php"><span class="token php language-php"><span class="token delimiter important"><?php</span>
<span class="token comment">/**
* @author Аты <[email protected]>
* @link https://www.phpdoc.org/docs/latest/index.html
*/</span>
<span class="token keyword">class</span> <span class="token class-name">DateTimeHelper</span>
<span class="token punctuation">{</span>
<span class="token comment">/**
* @param mixed $anything \DateTime объектына айналдыратын көшірме боларында не болмаса
*
* @throws \InvalidArgumentException
*
* @return \DateTime
*/</span>
<span class="token keyword">public</span> <span class="token keyword">function</span> <span class="token function">dateTimeFromAnything</span><span class="token punctuation">(</span><span class="token variable">$anything</span><span class="token punctuation">)</span>
<span class="token punctuation">{</span>
<span class="token variable">$type</span> <span class="token operator">=</span> <span class="token function">gettype</span><span class="token punctuation">(</span><span class="token variable">$anything</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token keyword">switch</span> <span class="token punctuation">(</span><span class="token variable">$type</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
<span class="token comment">// \DateTime объектына айналдыратын көшірме болары</span>
<span class="token punctuation">}</span>
<span class="token keyword">throw</span> <span class="token keyword">new</span> <span class="token class-name"><span class="token punctuation">\</span>InvalidArgumentException</span><span class="token punctuation">(</span>
<span class="token string">"Түрі '{$type}' болатын параметрді \DateTime объектына айналдырату сәтсіз болды"</span>
<span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>
<span class="token comment">/**
* @param mixed $date \DateTime объектына айналдыратын көшірме боларында не болмаса
*
* @return void
*/</span>
<span class="token keyword">public</span> <span class="token keyword">function</span> <span class="token function">printISO8601Date</span><span class="token punctuation">(</span><span class="token variable">$date</span><span class="token punctuation">)</span>
<span class="token punctuation">{</span>
<span class="token keyword">echo</span> <span class="token variable">$this</span><span class="token operator">-</span><span class="token operator">></span><span class="token function">dateTimeFromAnything</span><span class="token punctuation">(</span><span class="token variable">$date</span><span class="token punctuation">)</span><span class="token operator">-</span><span class="token operator">></span><span class="token function">format</span><span class="token punctuation">(</span><span class="token string">'c'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>
<span class="token comment">/**
* @param mixed $date \DateTime объектына айналдыратын көшірме боларында не болмаса
*/</span>
<span class="token keyword">public</span> <span class="token keyword">function</span> <span class="token function">printRFC2822Date</span><span class="token punctuation">(</span><span class="token variable">$date</span><span class="token punctuation">)</span>
<span class="token punctuation">{</span>
<span class="token keyword">echo</span> <span class="token variable">$this</span><span class="token operator">-</span><span class="token operator">></span><span class="token function">dateTimeFromAnything</span><span class="token punctuation">(</span><span class="token variable">$date</span><span class="token punctuation">)</span><span class="token operator">-</span><span class="token operator">></span><span class="token function">format</span><span class="token punctuation">(</span><span class="token string">'r'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>
<span class="token punctuation">}</span>
</span></code></pre>
<p>Сыныптың барлығы үшін бағдарламаны анықтау үшін <a href="https://docs.phpdoc.org/latest/guide/references/phpdoc/tags/author.html">@author</a> тегі мен <a href="https://docs.phpdoc.org/latest/guide/references/phpdoc/tags/link.html">@link</a> тегі бар. <a href="https://docs.phpdoc.org/latest/guide/references/phpdoc/tags/author.html">@author</a> тегі кодты жасаушыны анықтау үшін пайдаланылады және бірнеше жасаушыларды анықтау үшін қайталанады. <a href="https://docs.phpdoc.org/latest/guide/references/phpdoc/tags/link.html">@link</a> тегі кодпен веб-сайт арасында байланыс болатын веб-сайтқа сілтеме жасау үшін пайдаланылады.</p>
<p>Сынып ішінде бірінші өтініште параметрді өтінішке жататын түрі, атауы мен сипаттамасын анықтау үшін <a href="https://docs.phpdoc.org/latest/guide/references/phpdoc/tags/param.html">@param</a> тегі бар. Сонымен қатар, олдағы қайталанатын тіпті, <a href="https://docs.phpdoc.org/latest/guide/references/phpdoc/tags/return.html">@return</a> мен <a href="https://docs.phpdoc.org/latest/guide/references/phpdoc/tags/throws.html">@throws</a> тегтері бар, осында өтінішті беру түрі мен болатын боларды анықтау үшін.</p>
<p>Екінші және үшінші өтініштер өте ұсын болып табылады, жатталатын және жатталатын екінші және үшінші өтініштердің doc блоктарының арасында <a href="https://docs.phpdoc.org/latest/guide/references/phpdoc/tags/param.html">@param</a> тегі бар. Екінші және үшінші өтініштердің doc блоктарының маңызды айырмашылығы <a href="https://docs.phpdoc.org/latest/guide/references/phpdoc/tags/return.html">@return</a> тегінің қосу/жою мүмкіндігіні көрсету. <code>@return void</code> нақты мәлімет болмайды деп айтуында бізге хабарлама бар; тарихи шолу <code>@return void</code> ұсынбаса, сонымен қатар (қайтарым табылмаса) нәтиже барлық іс-шараларды бірге көздейді.</p>
</div>
</div>
</body>
</html>