Update doc generation #149
Conversation
|
@Jean-Beru , @StevenRenaux : should we sorts methods by names ? At the moment it is sorted by decalaration order I think. Which in case of refactoring makes it much harder to detect in documentation what changed and what didn't. Forcing the order by name would make this much easier BUT it would also make it less coherent because some methods might be better grouped together. WDYT should be the trade off ? |
|
I updated (without commit) the script to sort by name when working on the refactoring. It's perfect to see differences between 2 versions. But I think that it could only be done locally or in the CI (maybe by generating sorted n and n-1) to keep consistency in the documentation itself. The goal of this script should be generating documentation. |
|
I agree @Jean-Beru . Still it would make sense to keep it consistent. Because of traits it may generate noise on doc generation for no reasons. Enforcing sorting might be worth it. Regarding the CI I don't think we need the |
|
Should we add an annotation to allow grouping? |
|
maybe... The native |
src/Builder/CookieAwareTrait.php
Outdated
| @@ -12,6 +12,8 @@ trait CookieAwareTrait | |||
| /** | |||
| * Cookies to store in the Chromium cookie jar. (overrides any previous cookies). | |||
| * | |||
| * @package Behavior\\Chromium\\Cookie | |||
There was a problem hiding this comment.
WDYT of this way ? the value of package is only used for aggregation and sorting at the moment. It is not printed anywhere. Also should the @package be placed here or at the bottom of the phpdoc ?
| /** | ||
| * @see https://google.com | ||
| */ |
There was a problem hiding this comment.
It's like "find by yourself" ? 
docs/generate.php
Outdated
| $markdown = ''; | ||
|
|
||
| if ('' === $line) { | ||
| continue; | ||
| } | ||
| if (\count($seeList) > 0) { | ||
| $markdown .= '> [!TIP]'; | ||
| } | ||
|
|
||
| foreach ($seeList as $see) { | ||
| $markdown .= "\n> See: [{$see}]({$see})"; | ||
| } |
There was a problem hiding this comment.
if ([] === $seeList) {
return '';
}
$markdown = '> [!TIP]';
foreach ($seeList as $see) {
$markdown .= "\n> See: [{$see}]({$see})";
}
Description
Better parsing of phpdoc in case of multlines param + parsing each tag like
seeto be added as a tip@package@packageto group some method in documentation automatically