jenkins-bot has submitted this change and it was merged. Change subject: build: Test PHP documentation with Doxygen via composer and make pass ......................................................................
build: Test PHP documentation with Doxygen via composer and make pass This can be invoked with `composer run doc`. Have added a pre-doxygen filter written by Timo Tijhof for MediaWiki which improves its reading of our code, but it's imperfect even so. For example, Doxygen doesn't understand the type `string[]` for @var (but does for @param) so I've modified those to work. Change-Id: Ic64d3b46c1b9a6fe381d4c286325089620374bed --- M .gitignore M Doxyfile A build/doxygen-filter.php M composer.json M php/Element.php M php/mixins/GroupElement.php M php/widgets/ComboBoxInputWidget.php M php/widgets/DropdownInputWidget.php M php/widgets/RadioSelectInputWidget.php M phpcs.xml 10 files changed, 130 insertions(+), 14 deletions(-) Approvals: Bartosz Dziewoński: Looks good to me, approved Jforrester: Looks good to me, but someone else must approve jenkins-bot: Verified diff --git a/.gitignore b/.gitignore index bab5022..88b0536 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ /coverage /dist/* +/doc /docs node_modules npm-debug.log @@ -12,4 +13,3 @@ /demos/node_modules /demos/dist /demos/php - diff --git a/Doxyfile b/Doxyfile index a359f1a..7969e99 100644 --- a/Doxyfile +++ b/Doxyfile @@ -8,9 +8,14 @@ JAVADOC_AUTOBRIEF = YES QT_AUTOBRIEF = YES -WARN_NO_PARAMDOC = YES +QUIET = YES +WARNINGS = YES +WARN_IF_UNDOCUMENTED = NO +WARN_IF_DOC_ERROR = NO +WARN_NO_PARAMDOC = NO INPUT = README.md php/ +INPUT_FILTER = build/doxygen-filter.php FILE_PATTERNS = *.php RECURSIVE = YES # Requires doxygen 1.8.3+ diff --git a/build/doxygen-filter.php b/build/doxygen-filter.php new file mode 100755 index 0000000..8b9118d --- /dev/null +++ b/build/doxygen-filter.php @@ -0,0 +1,105 @@ +#!/usr/bin/php +<?php +/** + * Doxygen filter to show correct member variable types in documentation. + * + * Should be set in Doxygen INPUT_FILTER as "php build/doxygen-filter.php" + * + * Based on + * <http://virtualtee.blogspot.co.uk/2012/03/tip-for-using-doxygen-for-php-code.html> + * + * Taken from + * <http://git.wikimedia.org/blob/mediawiki%2Fcore.git/master/maintenance%2Fmwdoc-filter.php> + * + * Improved to resolve various bugs and better MediaWiki PHPDoc conventions: + * + * - Insert variable name after typehint instead of at end of line so that + * documentation text may follow after "@var Type". + * - Insert typehint into source code before $variable instead of inside the comment + * so that Doxygen interprets it. + * - Strip the text after @var from the output to avoid Doxygen warnings aboug bogus + * symbols being documented but not declared or defined. + * + * Copyright (C) 2012 Tamas Imrei <[email protected]> http://virtualtee.blogspot.com/ + * Copyright (C) 2015 Timo Tijhof + * + * Permission is hereby granted, free of charge, to any person obtaining + * a copy of this software and associated documentation files (the "Software"), + * to deal in the Software without restriction, including without limitation + * the rights to use, copy, modify, merge, publish, distribute, sublicense, + * and/or sell copies of the Software, and to permit persons to whom the + * Software is furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included + * in all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS + * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + * DEALINGS IN THE SOFTWARE. + */ + +if ( PHP_SAPI != 'cli' ) { + die( "This filter can only be run from the command line.\n" ); +} + +$source = file_get_contents( $argv[1] ); +$tokens = token_get_all( $source ); + +$buffer = $bufferType = null; +foreach ( $tokens as $token ) { + if ( is_string( $token ) ) { + if ( $buffer !== null && $token === ';' ) { + // If we still have a buffer and the statement has ended, + // flush it and move on. + echo $buffer; + $buffer = $bufferType = null; + } + echo $token; + continue; + } + list( $id, $content ) = $token; + switch ( $id ) { + case T_DOC_COMMENT: + // Escape slashes so that references to namespaces are not + // wrongly interpreted as a Doxygen "\command". + $content = addcslashes( $content, '\\' ); + // Look for instances of "@var Type" not followed by $name. + if ( preg_match( '#@var\s+([^\s]+)\s+([^\$]+)#s', $content ) ) { + $buffer = preg_replace_callback( + // Strip the "@var Type" part and remember the type + '#(@var\s+)([^\s]+)#s', + function ( $matches ) use ( &$bufferType ) { + $bufferType = $matches[2]; + return ''; + }, + $content + ); + } else { + echo $content; + } + break; + + case T_VARIABLE: + if ( $buffer !== null ) { + echo $buffer; + echo "$bufferType $content"; + $buffer = $bufferType = null; + } else { + echo $content; + } + break; + + default: + if ( $buffer !== null ) { + $buffer .= $content; + } else { + echo $content; + } + break; + } +} +?> diff --git a/composer.json b/composer.json index efabf35..d8b76b5 100644 --- a/composer.json +++ b/composer.json @@ -62,6 +62,9 @@ "parallel-lint . --exclude vendor", "phpcs -p", "phpunit $PHPUNIT_ARGS" + ], + "doc": [ + "doxygen" ] } } diff --git a/php/Element.php b/php/Element.php index a7bd683..d582940 100644 --- a/php/Element.php +++ b/php/Element.php @@ -39,17 +39,17 @@ protected $data = null; /** - * CSS classes explicitly configured for this element (as opposed to #$classes, which contains all - * classes for this element). + * Strings of the CSS classes explicitly configured for this element (as opposed to #$classes, + * which contains all classes for this element). * - * @var string[] + * @var array */ protected $ownClasses = array(); /** - * Mixins. + * ElementMixins. * - * @var ElementMixin[] List mixed in objects. + * @var array List mixed in objects. */ protected $mixins = array(); diff --git a/php/mixins/GroupElement.php b/php/mixins/GroupElement.php index 93d3c7a..1856515 100644 --- a/php/mixins/GroupElement.php +++ b/php/mixins/GroupElement.php @@ -9,9 +9,9 @@ */ class GroupElement extends ElementMixin { /** - * List of items in the group. + * List of items in the group as Elements. * - * @var Element[] + * @var array */ protected $items = array(); diff --git a/php/widgets/ComboBoxInputWidget.php b/php/widgets/ComboBoxInputWidget.php index e8e4208..77d2e91 100644 --- a/php/widgets/ComboBoxInputWidget.php +++ b/php/widgets/ComboBoxInputWidget.php @@ -9,8 +9,8 @@ class ComboBoxInputWidget extends TextInputWidget { /** - * HTML `<option>` tags for this widget. - * @var Tag[] + * HTML `<option>` tags for this widget, as Tags. + * @var array */ protected $options = array(); diff --git a/php/widgets/DropdownInputWidget.php b/php/widgets/DropdownInputWidget.php index f8ea48a..40e3112 100644 --- a/php/widgets/DropdownInputWidget.php +++ b/php/widgets/DropdownInputWidget.php @@ -9,8 +9,8 @@ class DropdownInputWidget extends InputWidget { /** - * HTML `<option>` tags for this widget. - * @var Tag[] + * HTML `<option>` tags for this widget, as Tags. + * @var array */ protected $options = array(); diff --git a/php/widgets/RadioSelectInputWidget.php b/php/widgets/RadioSelectInputWidget.php index 912c691..5c6c44c 100644 --- a/php/widgets/RadioSelectInputWidget.php +++ b/php/widgets/RadioSelectInputWidget.php @@ -19,7 +19,9 @@ protected $name = null; /** - * @var FieldLayout[] + * Layouts for this input, as FieldLayouts. + * + * @var array */ protected $fields = array(); diff --git a/phpcs.xml b/phpcs.xml index adeac4f..593bd95 100644 --- a/phpcs.xml +++ b/phpcs.xml @@ -4,6 +4,7 @@ <file>.</file> <arg name="encoding" value="UTF-8"/> <arg name="extensions" value="php"/> + <exclude-pattern>build</exclude-pattern> <exclude-pattern>coverage</exclude-pattern> <exclude-pattern>vendor</exclude-pattern> <exclude-pattern>demos/pages</exclude-pattern> -- To view, visit https://gerrit.wikimedia.org/r/254492 To unsubscribe, visit https://gerrit.wikimedia.org/r/settings Gerrit-MessageType: merged Gerrit-Change-Id: Ic64d3b46c1b9a6fe381d4c286325089620374bed Gerrit-PatchSet: 2 Gerrit-Project: oojs/ui Gerrit-Branch: master Gerrit-Owner: Jforrester <[email protected]> Gerrit-Reviewer: Bartosz Dziewoński <[email protected]> Gerrit-Reviewer: Esanders <[email protected]> Gerrit-Reviewer: Jforrester <[email protected]> Gerrit-Reviewer: Krinkle <[email protected]> Gerrit-Reviewer: Legoktm <[email protected]> Gerrit-Reviewer: Reedy <[email protected]> Gerrit-Reviewer: jenkins-bot <> _______________________________________________ MediaWiki-commits mailing list [email protected] https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
