diff --git a/autotest.sh b/autotest.sh
index 3ce88c649747e49eb6f75c1091995a9b30ba7c2a..8e99c8f0ca9937e055ae9621e6e0b481c5a02196 100755
--- a/autotest.sh
+++ b/autotest.sh
@@ -89,6 +89,9 @@ if [ "$1" ]; then
fi
fi
+# check for the presence of @since in all OCP methods
+$PHP build/OCPSinceChecker.php
+
# Back up existing (dev) config if one exists and backup not already there
if [ -f config/config.php ] && [ ! -f config/config-autotest-backup.php ]; then
mv config/config.php config/config-autotest-backup.php
diff --git a/build/OCPSinceChecker.php b/build/OCPSinceChecker.php
new file mode 100644
index 0000000000000000000000000000000000000000..c059b687393378ba0c4bd76b9b29b58e150246d3
--- /dev/null
+++ b/build/OCPSinceChecker.php
@@ -0,0 +1,115 @@
+<?php
+/**
+ * @author Morris Jobke <hey@morrisjobke.de>
+ *
+ * @copyright Copyright (c) 2015, ownCloud, Inc.
+ * @license AGPL-3.0
+ *
+ * This code is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License, version 3,
+ * as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License, version 3,
+ * along with this program. If not, see <http://www.gnu.org/licenses/>
+ *
+ */
+
+
+require_once(dirname(__DIR__) . '/3rdparty/autoload.php');
+
+/**
+ * Class SinceTagCheckVisitor
+ *
+ * this class checks all methods for the presence of the @since tag
+ */
+class SinceTagCheckVisitor extends \PhpParser\NodeVisitorAbstract {
+
+ /** @var string */
+ protected $namespace = '';
+ /** @var string */
+ protected $className = '';
+ /** @var bool */
+ protected $deprecatedClass = false;
+
+ /** @var array */
+ protected $errors = [];
+
+ public function enterNode(\PhpParser\Node $node) {
+ if($this->deprecatedClass) {
+ return;
+ }
+
+ if($node instanceof \PhpParser\Node\Stmt\Namespace_) {
+ $this->namespace = $node->name;
+ }
+
+ if($node instanceof \PhpParser\Node\Stmt\Interface_ or
+ $node instanceof \PhpParser\Node\Stmt\Class_) {
+ $this->className = $node->name;
+
+ /** @var \PhpParser\Comment\Doc[] $comments */
+ $comments = $node->getAttribute('comments');
+ if(count($comments) !== 0) {
+ $comment = $comments[count($comments) - 1];
+ $text = $comment->getText();
+ if(strpos($text, '@deprecated') !== false) {
+ $this->deprecatedClass = true;
+ }
+ }
+ }
+
+ if($node instanceof \PhpParser\Node\Stmt\ClassMethod) {
+ /** @var \PhpParser\Node\Stmt\ClassMethod $node */
+ /** @var \PhpParser\Comment\Doc[] $comments */
+ $comments = $node->getAttribute('comments');
+
+ if(count($comments) === 0) {
+ $this->errors[] = 'PHPDoc is needed for ' . $this->namespace . '\\' . $this->className . '::' . $node->name;
+ return;
+ }
+ $comment = $comments[count($comments) - 1];
+ $text = $comment->getText();
+ if(strpos($text, '@since') === false && strpos($text, '@deprecated') === false) {
+ $this->errors[] = '@since or @deprecated tag is needed in PHPDoc for ' . $this->namespace . '\\' . $this->className . '::' . $node->name;
+ return;
+ }
+ }
+ }
+
+ public function getErrors() {
+ return $this->errors;
+ }
+}
+
+echo 'Parsing all files in lib/public for the presence of @since or @deprecated on each method...' . PHP_EOL . PHP_EOL;
+
+
+$parser = new PhpParser\Parser(new PhpParser\Lexer);
+
+/* iterate over all .php files in lib/public */
+$Directory = new RecursiveDirectoryIterator(dirname(__DIR__) . '/lib/public');
+$Iterator = new RecursiveIteratorIterator($Directory);
+$Regex = new RegexIterator($Iterator, '/^.+\.php$/i', RecursiveRegexIterator::GET_MATCH);
+
+$errors = [];
+
+foreach($Regex as $file) {
+ $stmts = $parser->parse(file_get_contents($file[0]));
+
+ $visitor = new SinceTagCheckVisitor($this->blackListedClassNames);
+ $traverser = new \PhpParser\NodeTraverser();
+ $traverser->addVisitor($visitor);
+ $traverser->traverse($stmts);
+
+ $errors = array_merge($errors, $visitor->getErrors());
+}
+
+if(count($errors)) {
+ echo join(PHP_EOL, $errors) . PHP_EOL . PHP_EOL;
+ exit(1);
+}
diff --git a/lib/public/appframework/db/doesnotexistexception.php b/lib/public/appframework/db/doesnotexistexception.php
index 6df0477498c1ea84e925da78ee9518ed2a23af1b..2cefa0fe827f4f4ec5d4c8a0b1599ae0e838ade5 100644
--- a/lib/public/appframework/db/doesnotexistexception.php
+++ b/lib/public/appframework/db/doesnotexistexception.php
@@ -34,6 +34,7 @@ class DoesNotExistException extends \Exception {
/**
* Constructor
* @param string $msg the error message
+ * @since 7.0.0
*/
public function __construct($msg){
parent::__construct($msg);
diff --git a/lib/public/appframework/db/entity.php b/lib/public/appframework/db/entity.php
index a12f759357e3f10c1072b821dbf4f8bf8730d226..f7beebef154f68df68049f3615d5514c448d9021 100644
--- a/lib/public/appframework/db/entity.php
+++ b/lib/public/appframework/db/entity.php
@@ -92,6 +92,10 @@ abstract class Entity {
$this->_updatedFields = array();
}
+ /**
+ * Generic setter for properties
+ * @since 7.0.0
+ */
protected function setter($name, $args) {
// setters should only work for existing attributes
if(property_exists($this, $name)){
@@ -112,6 +116,10 @@ abstract class Entity {
}
}
+ /**
+ * Generic getter for properties
+ * @since 7.0.0
+ */
protected function getter($name) {
// getters should only work for existing attributes
if(property_exists($this, $name)){
@@ -148,6 +156,7 @@ abstract class Entity {
/**
* Mark am attribute as updated
* @param string $attribute the name of the attribute
+ * @since 7.0.0
*/
protected function markFieldUpdated($attribute){
$this->_updatedFields[$attribute] = true;
@@ -212,6 +221,7 @@ abstract class Entity {
* that value once its being returned from the database
* @param string $fieldName the name of the attribute
* @param string $type the type which will be used to call settype()
+ * @since 7.0.0
*/
protected function addType($fieldName, $type){
$this->_fieldTypes[$fieldName] = $type;
diff --git a/lib/public/appframework/db/mapper.php b/lib/public/appframework/db/mapper.php
index 157bea369167589f7f3e362b1a12e1d3a5b37966..2b99c99b71e548a88912f67e36aaf0df70ee66cd 100644
--- a/lib/public/appframework/db/mapper.php
+++ b/lib/public/appframework/db/mapper.php
@@ -193,6 +193,7 @@ abstract class Mapper {
* Checks if an array is associative
* @param array $array
* @return bool true if associative
+ * @since 8.1.0
*/
private function isAssocArray(array $array) {
return array_values($array) !== $array;
@@ -202,6 +203,7 @@ abstract class Mapper {
* Returns the correct PDO constant based on the value type
* @param $value
* @return PDO constant
+ * @since 8.1.0
*/
private function getPDOType($value) {
switch (gettype($value)) {
diff --git a/lib/public/appframework/db/multipleobjectsreturnedexception.php b/lib/public/appframework/db/multipleobjectsreturnedexception.php
index cdfb748b145872c40a064e61f5d97fd8e18d63c8..988bf6bb03382a558fdf9c9aa49752ddfe193374 100644
--- a/lib/public/appframework/db/multipleobjectsreturnedexception.php
+++ b/lib/public/appframework/db/multipleobjectsreturnedexception.php
@@ -34,6 +34,7 @@ class MultipleObjectsReturnedException extends \Exception {
/**
* Constructor
* @param string $msg the error message
+ * @since 7.0.0
*/
public function __construct($msg){
parent::__construct($msg);
diff --git a/lib/public/defaults.php b/lib/public/defaults.php
index 2d55a64f002ff535fbc0da162c0039b198e5738c..723c6ecbb789d23bb19f630d5c5ac40e0df8fa33 100644
--- a/lib/public/defaults.php
+++ b/lib/public/defaults.php
@@ -48,6 +48,7 @@ class Defaults {
/**
* creates a \OC_Defaults instance which is used in all methods to retrieve the
* actual defaults
+ * @since 6.0.0
*/
function __construct() {
$this->defaults = new \OC_Defaults();
diff --git a/lib/public/files/folder.php b/lib/public/files/folder.php
index f5f91e8158cad6e98b0f608f2995e3a088109d4d..533e490634fcf59db27b327f4b856b203b9f0730 100644
--- a/lib/public/files/folder.php
+++ b/lib/public/files/folder.php
@@ -107,6 +107,7 @@ interface Folder extends Node {
* @param string $path relative path of the new file
* @return \OCP\Files\File
* @throws \OCP\Files\NotPermittedException
+ * @since 6.0.0
*/
public function newFile($path);
diff --git a/lib/public/files/locknotacquiredexception.php b/lib/public/files/locknotacquiredexception.php
index 66e131ab1e5b93930faac34f679e50ae5b3ddee2..d078ff34818dbf18861a9472605a93ff140c066b 100644
--- a/lib/public/files/locknotacquiredexception.php
+++ b/lib/public/files/locknotacquiredexception.php
@@ -41,12 +41,20 @@ class LockNotAcquiredException extends \Exception {
/** @var integer $lockType The type of the lock that was attempted */
public $lockType;
+ /**
+ * @since 7.0.0
+ */
public function __construct($path, $lockType, $code = 0, \Exception $previous = null) {
$message = \OC::$server->getL10N('core')->t('Could not obtain lock type %d on "%s".', array($lockType, $path));
parent::__construct($message, $code, $previous);
}
- // custom string representation of object
+ /**
+ * custom string representation of object
+ *
+ * @return string
+ * @since 7.0.0
+ */
public function __toString() {
return __CLASS__ . ": [{$this->code}]: {$this->message}\n";
}
diff --git a/lib/public/iuser.php b/lib/public/iuser.php
index 393ab90d2608c9adda0e55973068f5abe64365fe..6cbcfbf23120098c407c5c790dac9e723ce54bc8 100644
--- a/lib/public/iuser.php
+++ b/lib/public/iuser.php
@@ -93,6 +93,7 @@ interface IUser {
* get the users home folder to mount
*
* @return string
+ * @since 8.0.0
*/
public function getHome();
@@ -116,6 +117,7 @@ interface IUser {
* check if the backend supports changing passwords
*
* @return bool
+ * @since 8.0.0
*/
public function canChangePassword();
diff --git a/lib/public/iusermanager.php b/lib/public/iusermanager.php
index 212d21759b09410d904f80d8dc77e7b8a4807717..e3857d6231a68b8861c01e2f7a86e960cfbd5ffc 100644
--- a/lib/public/iusermanager.php
+++ b/lib/public/iusermanager.php
@@ -64,6 +64,7 @@ interface IUserManager {
/**
* remove all user backends
+ * @since 8.0.0
*/
public function clearBackends() ;