MAGETWO-64523: Add static test on forbidden "final" keyword and eliminate it usage in code

 - added doc blocks for new methods

Author: Volodymyr Kublytskyi

dev/tests/static/testsuite/Magento/Test/Php/LiveCodeTest.php

@@ -85,6 +85,21 @@ public static function getWhitelist($fileTypes = ['php'], $changedFilesBaseDir =
         return $targetFiles;
     }
 
+    /**
+     * This method loads list of changed files.
+     *
+     * List may be generated by:
+     *  - dev/tests/static/get_github_changes.php utility (allow to generate diffs between branches),
+     *  - CLI command "git diff --name-only > dev/tests/static/testsuite/Magento/Test/_files/changed_files_local.txt",
+     *
+     * If no generated changed files list found "git diff" will be used to find not committed changed
+     * (tests should be invoked from target gir repo).
+     *
+     * Note: "static" modifier used for compatibility with legacy implementation of self::getWhitelist method
+     *
+     * @param string $changedFilesBaseDir Base dir with previously generated list files
+     * @return string[] List of changed files
+     */
     private static function getChangedFilesList($changedFilesBaseDir)
     {
         $changedFiles = [];
@@ -113,6 +128,21 @@ function (&$file) {
         return $changedFiles;
     }
 
+    /**
+     * Filter list of files.
+     *
+     * File removed from list:
+     *  - if it not exists,
+     *  - if allowed types are specified and file has another type (extension),
+     *  - if allowed directories specified and file not located in one of them.
+     *
+     * Note: "static" modifier used for compatibility with legacy implementation of self::getWhitelist method
+     *
+     * @param string[] $files List of file paths to filter
+     * @param string[] $allowedFileTypes List of allowed file extensions (pass empty array to allow all)
+     * @param string[] $allowedDirectories List of allowed directories (pass empty array to allow all)
+     * @return string[] Filtered file paths
+     */
     private static function filterFiles(array $files, array $allowedFileTypes, array $allowedDirectories)
     {
         if (empty($allowedFileTypes)) {