Skip to content

Commit 45babf1

Browse files
jubianchijubianchi
committed
Merge pull request #4 from agallou/description_methods
add description on methods
2 parents 19b45df + b4745b4 commit 45babf1

24 files changed

+2805
-15
lines changed

‎.gitattributes

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
bin/updateDoc export-ignore

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
tmp/

‎bin/updateDoc

Lines changed: 317 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,317 @@
1+
#!/usr/bin/env php
2+
<?php
3+
4+
function parseFile($filename)
5+
{
6+
$helps = array();
7+
$previousLine = null;
8+
$currentAsserter = null;
9+
$currentMethod = null;
10+
$level3Name = null;
11+
foreach (new \SplFileObject($filename) as $line) {
12+
$line = rtrim($line);
13+
if (preg_match('/^[=]+$/', $line)) {
14+
$currentAsserter = strtolower($previousLine);
15+
$helps['level1'][$currentAsserter] = array();
16+
$helps['level1'][$currentAsserter]['level2'][$currentMethod]['content'] = '';
17+
$previousLine = $line;
18+
$level3Name = null;
19+
$currentMethod = null;
20+
continue;
21+
}
22+
23+
if (preg_match('/^[-]+$/', $line)) {
24+
$currentMethod = strtolower($previousLine);
25+
$helps['level1'][$currentAsserter]['level2'][$currentMethod]['content'] = '';
26+
$previousLine = $line;
27+
$level3Name = null;
28+
continue;
29+
}
30+
31+
if (preg_match('/^[~]+$/', $line)) {
32+
$level3Name = strtolower($previousLine);
33+
$helps['level1'][$currentAsserter]['level2'][$currentMethod]['level3'][$level3Name]['content'] = '';
34+
$previousLine = $line;
35+
continue;
36+
}
37+
38+
if(null !== $currentAsserter) {
39+
if (null === $currentMethod) {
40+
$helps['level1'][$currentAsserter]['content'] .= $previousLine . PHP_EOL;
41+
} else {
42+
if (null !== $level3Name) {
43+
$helps['level1'][$currentAsserter]['level2'][$currentMethod]['level3'][$level3Name]['content'] .= $previousLine . PHP_EOL;
44+
} else {
45+
$helps['level1'][$currentAsserter]['level2'][$currentMethod]['content'] .= $previousLine . PHP_EOL;
46+
}
47+
}
48+
}
49+
50+
51+
52+
$previousLine = $line;
53+
}
54+
55+
if (null !== $currentAsserter && null !== $currentMethod) {
56+
$helps['level1'][$currentAsserter]['level2'][$currentMethod]['content'] .= $previousLine . PHP_EOL;
57+
}
58+
59+
foreach ($helps['level1'] as $asserter => $methods) {
60+
61+
$explodedHelpLv1Content = explode(PHP_EOL, $methods['content']);
62+
$explodedHelpLv1Content = ltrimArray($explodedHelpLv1Content);
63+
$explodedHelpLv1Content = rtrimArray($explodedHelpLv1Content);
64+
$helps['level1'][$asserter]['content'] = implode(PHP_EOL, $explodedHelpLv1Content);
65+
66+
foreach ($methods['level2'] as $methodName => $help) {
67+
$explodedHelp = explode(PHP_EOL, $help['content']);
68+
$explodedHelp = ltrimArray($explodedHelp);
69+
$explodedHelp = rtrimArray($explodedHelp);
70+
$helps['level1'][$asserter]['level2'][$methodName]['content'] = implode(PHP_EOL, $explodedHelp);
71+
if (isset($helps['level1'][$asserter]['level2'][$methodName]['level3'])) {
72+
foreach ($helps['level1'][$asserter]['level2'][$methodName]['level3'] as $level3Name => $helpLvl3) {
73+
$explodedHelp = explode(PHP_EOL, $helpLvl3['content']);
74+
$explodedHelp = ltrimArray($explodedHelp);
75+
$explodedHelp = rtrimArray($explodedHelp);
76+
$helps['level1'][$asserter]['level2'][$methodName]['level3'][$level3Name]['content'] = implode(PHP_EOL, $explodedHelp);
77+
}
78+
}
79+
}
80+
}
81+
82+
return $helps;
83+
}
84+
85+
function ltrimArray(array $array) {
86+
$tmpArray = array();
87+
$isArrayBegin = true;
88+
foreach ($array as $line) {
89+
if ($isArrayBegin && (preg_match('/^[-~=]+$/', $line) || 0 === strlen(trim($line)))) {
90+
continue;
91+
}
92+
$isArrayBegin = false;
93+
$tmpArray[] = $line;
94+
}
95+
96+
97+
return $tmpArray;
98+
}
99+
100+
function rtrimArray(array $array) {
101+
return array_reverse(ltrimArray(array_reverse($array)));
102+
}
103+
104+
function getLevel2Content(array $helps, $level1Name, $level2Name)
105+
{
106+
if (!isset($helps['level1'][$level1Name]['level2'][$level2Name])) {
107+
throw new \RuntimeException(sprintf('Class : %s, Method %s. Documentation not found', $level1Name, $level2Name));
108+
}
109+
110+
return $helps['level1'][$level1Name]['level2'][$level2Name]['content'];
111+
}
112+
113+
function getMethodHelp(\ReflectionMethod $method, array $helps)
114+
{
115+
$shortClassname = strtolower($method->getDeclaringClass()->getShortName());
116+
$methodName = strtolower($method->getName());
117+
return getLevel2Content($helps, $shortClassname, $methodName);
118+
}
119+
120+
function getPropertyHelp(\ReflectionProperty $property, array $helps)
121+
{
122+
$shortClassname = strtolower($property->getDeclaringClass()->getShortName());
123+
$methodName = strtolower($property->getName());
124+
return getLevel2Content($helps, $shortClassname, $methodName);
125+
}
126+
127+
function getClassHelp(\ReflectionClass $class, array $helps)
128+
{
129+
$shortClassname = strtolower($class->getShortName());
130+
131+
if (!isset($helps['level1'][$shortClassname])) {
132+
throw new \RuntimeException(sprintf('Class : %s. Documentation not found', $shortClassname));
133+
}
134+
135+
return $helps['level1'][$shortClassname]['content'];
136+
}
137+
138+
function applyMappings(array $helps)
139+
{
140+
$helps['level1']['phpstring'] = $helps['level1']['string'];
141+
$helps['level1']['phparray'] = $helps['level1']['array'];
142+
$helps['level1']['phpclass'] = $helps['level1']['class'];
143+
$helps['level1']['phpfloat'] = $helps['level1']['float'];
144+
$helps['level1']['adapter'] = array_merge($helps['level1']['mock']['level2']['call'], $helps['level1']['mock']);
145+
$helps['level1']['adapter']['level2'] = array_merge($helps['level1']['adapter']['level2'], $helps['level1']['adapter']['level3']);
146+
unset($helps['level1']['adapter']['level3']);
147+
$helps['level1']['adapter']['level2']['once'] = $helps['level1']['adapter']['level2']['once/twice/thrice'];
148+
$helps['level1']['adapter']['level2']['twice'] = $helps['level1']['adapter']['level2']['once/twice/thrice'];
149+
$helps['level1']['adapter']['level2']['thrice'] = $helps['level1']['adapter']['level2']['once/twice/thrice'];
150+
return $helps;
151+
}
152+
153+
function replaceHelpDoc($docComment, $spacesCount, \closure $helpCallback)
154+
{
155+
$docComment = explode(PHP_EOL, $docComment);
156+
$firstAnnotation = 0;
157+
158+
foreach ($docComment as $k => $comment)
159+
{
160+
if (preg_match('/^\s+\*\s+@/', $comment) || (preg_match('/^\s+\*\//', $comment)))
161+
{
162+
$firstAnnotation = $k;
163+
164+
break;
165+
}
166+
}
167+
168+
try {
169+
$methodHelpLines = explode(PHP_EOL, $helpCallback());
170+
$methodHelpLines[] = '';
171+
} catch (\RuntimeException $e) {
172+
return implode(PHP_EOL, $docComment);
173+
}
174+
175+
176+
if (count($methodHelpLines) === 1 && $methodHelpLines[0] == '') {
177+
return implode(PHP_EOL, $docComment);
178+
}
179+
180+
$methodHelp = '';
181+
foreach ($methodHelpLines as $methodHelpLine) {
182+
$methodHelpLine = preg_replace('/^.. (\w+)::/', '$1: ', $methodHelpLine);
183+
$methodHelpLine = preg_replace('/:ref:`(\w+) <.*?>`/', '$1', $methodHelpLine);
184+
185+
if (preg_match('/^\s*..\s+[\w\-]+:/', $methodHelpLine)) {
186+
continue;
187+
}
188+
189+
if (preg_match('/^\s+\|\s/', $methodHelpLine)) {
190+
$methodHelpLine = ltrim($methodHelpLine, ' |');
191+
}
192+
193+
$methodHelp .= str_repeat(' ', $spacesCount) . '* ' . rtrim($methodHelpLine) . PHP_EOL;
194+
}
195+
196+
$methodHelp = preg_replace('/(?:\s{' . $spacesCount . '}\*\s*\n)+/', str_repeat(' ', $spacesCount) . '*' . PHP_EOL, $methodHelp);
197+
$methodHelp = rtrim($methodHelp);
198+
199+
$doc = '/**' . PHP_EOL;
200+
$doc .= $methodHelp;
201+
$doc .= $methodHelp !== '' ? PHP_EOL : '';
202+
$doc .= implode(PHP_EOL, array_slice($docComment, $firstAnnotation));
203+
204+
return $doc;
205+
}
206+
207+
208+
function replaceInFile($file, $docComment, $newDocComment, $suffix)
209+
{
210+
return file_put_contents(
211+
$file,
212+
preg_replace_callback(
213+
sprintf('/(%s)([\w\s]+%s)/msi', preg_quote($docComment, '/'), preg_quote($suffix, '/s')),
214+
function ($matches) use ($newDocComment) {
215+
return $newDocComment . $matches[2];
216+
},
217+
file_get_contents($file)
218+
)
219+
);
220+
}
221+
222+
function updateFile($file, $className, array $helps)
223+
{
224+
$refectionClass = new \ReflectionClass($className);
225+
foreach ($refectionClass->getMethods() as $method) {
226+
if ($className != $method->getDeclaringClass()->getName()) {
227+
continue;
228+
}
229+
230+
if (strtolower($method->getName()) == 'isreferenceto') {
231+
continue;
232+
}
233+
234+
$newDocComment = replaceHelpDoc(
235+
$method->getDocComment(),
236+
5,
237+
function() use ($helps, $method) {
238+
return getMethodHelp($method, $helps);
239+
}
240+
);
241+
242+
replaceInFile($file, $method->getDocComment(), $newDocComment, 'function ' . $method->getName() . "(");
243+
}
244+
245+
foreach ($refectionClass->getProperties() as $property) {
246+
if ($className != $property->getDeclaringClass()->getName()) {
247+
continue;
248+
}
249+
250+
$newPropertyDocComment = replaceHelpDoc(
251+
$property->getDocComment(),
252+
5,
253+
function() use ($helps, $property){
254+
return getPropertyHelp($property, $helps);
255+
}
256+
);
257+
258+
replaceInFile($file, $property->getDocComment(), $newPropertyDocComment, 'public $' . $property->getName() . ";");
259+
}
260+
261+
if (false !== $refectionClass->getDocComment()) {
262+
$newClassDocComment = replaceHelpDoc(
263+
$refectionClass->getDocComment(),
264+
1,
265+
function() use ($helps, $refectionClass){
266+
return getClassHelp($refectionClass, $helps);
267+
}
268+
);
269+
replaceInFile($file, $refectionClass->getDocComment(), $newClassDocComment, $refectionClass->getShortName());
270+
}
271+
}
272+
273+
passthru('rm -rf tmp && mkdir -p tmp && cd tmp && git clone https://github.com/atoum/atoum-documentation.git && cd atoum-documentation && ./builddoc text');
274+
275+
$assertersDocFile = 'tmp/atoum-documentation/build/en/text/asserters.txt';
276+
277+
//be careful with the order of the class (because of some extends)
278+
$asserters = array(
279+
'classes/mageekguy/atoum/stubs/asserters/variable.php',
280+
'classes/mageekguy/atoum/stubs/asserters/boolean.php',
281+
'classes/mageekguy/atoum/stubs/asserters/object.php',
282+
'classes/mageekguy/atoum/stubs/asserters/dateInterval.php',
283+
'classes/mageekguy/atoum/stubs/asserters/dateTime.php',
284+
'classes/mageekguy/atoum/stubs/asserters/error.php',
285+
'classes/mageekguy/atoum/stubs/asserters/exception.php',
286+
'classes/mageekguy/atoum/stubs/asserters/phpString.php',
287+
'classes/mageekguy/atoum/stubs/asserters/hash.php',
288+
'classes/mageekguy/atoum/stubs/asserters/integer.php',
289+
'classes/mageekguy/atoum/stubs/asserters/phpArray.php',
290+
'classes/mageekguy/atoum/stubs/asserters/phpClass.php',
291+
'classes/mageekguy/atoum/stubs/asserters/phpFloat.php',
292+
'classes/mageekguy/atoum/stubs/asserters/adapter.php',
293+
'classes/mageekguy/atoum/stubs/asserters/mock.php',
294+
'classes/mageekguy/atoum/stubs/asserters/mysqlDateTime.php',
295+
'classes/mageekguy/atoum/stubs/asserters/castToString.php',
296+
'classes/mageekguy/atoum/stubs/asserters/sizeOf.php',
297+
'classes/mageekguy/atoum/stubs/asserters/stream.php',
298+
'classes/mageekguy/atoum/stubs/asserters/utf8String.php',
299+
'classes/mageekguy/atoum/stubs/asserters/output.php',
300+
);
301+
302+
include 'classes/mageekguy/atoum/stubs/asserters.php';
303+
foreach ($asserters as $asserter) {
304+
include $asserter;
305+
}
306+
307+
$helps = parseFile($assertersDocFile);
308+
309+
$helps = applyMappings($helps);
310+
311+
foreach ($asserters as $asserter) {
312+
$path = explode('/', $asserter);
313+
$filename = array_pop($path);
314+
$className = pathinfo($filename, PATHINFO_FILENAME);
315+
updateFile($asserter, 'mageekguy\\atoum\\stubs\\asserters\\' . $className, $helps);
316+
}
317+

0 commit comments

Comments
 (0)