From eeb9103e267a01ad5f076afeb02bedabfcc70db9 Mon Sep 17 00:00:00 2001 From: Klaus Weidenbach Date: Fri, 5 May 2017 00:23:57 +0200 Subject: :bulb: correct some Doxygen syntax mistakes. --- include/channel.php | 130 ++++++++++++++++++++++++++++---------------------- include/feedutils.php | 7 ++- include/import.php | 19 +++++--- include/items.php | 30 ++++++------ include/text.php | 15 +++--- 5 files changed, 114 insertions(+), 87 deletions(-) (limited to 'include') diff --git a/include/channel.php b/include/channel.php index 0a4c9009a..31dca1ae5 100644 --- a/include/channel.php +++ b/include/channel.php @@ -57,8 +57,9 @@ function identity_check_service_class($account_id) { * Plugins can set additional policies such as full name requirements, character * sets, multi-byte length, etc. * + * @hooks validate_channelname + * * \e array \b name * @param string $name - * * @returns nil return if name is valid, or string describing the error state. */ function validate_channelname($name) { @@ -69,7 +70,7 @@ function validate_channelname($name) { if (strlen($name) > 255) return t('Name too long'); - $arr = array('name' => $name); + $arr = ['name' => $name]; call_hooks('validate_channelname', $arr); if (x($arr, 'message')) @@ -463,7 +464,6 @@ function create_identity($arr) { * if true, set this default unconditionally * if $force is false only do this if there is no existing default */ - function set_default_login_identity($account_id, $channel_id, $force = true) { $r = q("select account_default_channel from account where account_id = %d limit 1", intval($account_id) @@ -478,12 +478,29 @@ function set_default_login_identity($account_id, $channel_id, $force = true) { } } - +/** + * @brief Return an array with default list of sections to export. + * + * @hooks get_default_export_sections + * * \e array \b sections + * @return array with default section names to export + */ function get_default_export_sections() { - $sections = [ 'channel', 'connections', 'config', 'apps', 'chatrooms', 'events', 'webpages', 'mail', 'wikis' ]; + $sections = [ + 'channel', + 'connections', + 'config', + 'apps', + 'chatrooms', + 'events', + 'webpages', + 'mail', + 'wikis' + ]; $cb = [ 'sections' => $sections ]; call_hooks('get_default_export_sections', $cb); + return $cb['sections']; } @@ -493,15 +510,17 @@ function get_default_export_sections() { * which would be necessary to create a nomadic identity clone. This includes * most channel resources and connection information with the exception of content. * + * @hooks identity_basic_export + * * \e int \b channel_id + * * \e array \b sections + * * \e array \b data * @param int $channel_id * Channel_id to export - * @param boolean $items - * Include channel posts (wall items), default false - * + * @param array $sections (optional) + * Which sections to include in the export, default see get_default_export_sections() * @returns array * See function for details */ - function identity_basic_export($channel_id, $sections = null) { /* @@ -511,16 +530,16 @@ function identity_basic_export($channel_id, $sections = null) { if(! $sections) { $sections = get_default_export_sections(); } - + $ret = []; // use constants here as otherwise we will have no idea if we can import from a site // with a non-standard platform and version. $ret['compatibility'] = [ - 'project' => PLATFORM_NAME, - 'version' => STD_VERSION, - 'database' => DB_UPDATE_VERSION, + 'project' => PLATFORM_NAME, + 'version' => STD_VERSION, + 'database' => DB_UPDATE_VERSION, 'server_role' => Zotlabs\Lib\System::get_server_role() ]; @@ -549,8 +568,7 @@ function identity_basic_export($channel_id, $sections = null) { if($r) $ret['profile'] = $r; - - $r = q("select mimetype, content, os_storage from photo + $r = q("select mimetype, content, os_storage from photo where imgscale = 4 and photo_usage = %d and uid = %d limit 1", intval(PHOTO_PROFILE), intval($channel_id) @@ -558,8 +576,8 @@ function identity_basic_export($channel_id, $sections = null) { if($r) { $ret['photo'] = [ - 'type' => $r[0]['mimetype'], - 'data' => (($r[0]['os_storage']) + 'type' => $r[0]['mimetype'], + 'data' => (($r[0]['os_storage']) ? base64url_encode(file_get_contents($r[0]['content'])) : base64url_encode($r[0]['content'])) ]; } @@ -605,7 +623,6 @@ function identity_basic_export($channel_id, $sections = null) { ); if($r) $ret['group_member'] = $r; - } if(in_array('config',$sections)) { @@ -614,7 +631,7 @@ function identity_basic_export($channel_id, $sections = null) { ); if($r) $ret['config'] = $r; - + // All other term types will be included in items, if requested. $r = q("select * from term where ttype in (%d,%d) and uid = %d", @@ -641,7 +658,6 @@ function identity_basic_export($channel_id, $sections = null) { if($r) $ret['likes'] = $r; - } if(in_array('apps',$sections)) { @@ -667,7 +683,6 @@ function identity_basic_export($channel_id, $sections = null) { $ret['chatroom'] = $r; } - if(in_array('events',$sections)) { $r = q("select * from event where uid = %d", intval($channel_id) @@ -697,7 +712,7 @@ function identity_basic_export($channel_id, $sections = null) { $ret['menu'][] = menu_element($ret['channel'],$m); } } - $r = q("select * from item where item_type in ( " + $r = q("select * from item where item_type in ( " . ITEM_TYPE_BLOCK . "," . ITEM_TYPE_PDL . "," . ITEM_TYPE_WEBPAGE . " ) and uid = %d", intval($channel_id) ); @@ -707,7 +722,6 @@ function identity_basic_export($channel_id, $sections = null) { $r = fetch_post_tags($r,true); foreach($r as $rr) $ret['webpages'][] = encode_item($rr,true); - } } @@ -758,7 +772,7 @@ function identity_basic_export($channel_id, $sections = null) { * Don't export linked resource items. we'll have to pull those out separately. */ - $r = q("select * from item where item_wall = 1 and item_deleted = 0 and uid = %d + $r = q("select * from item where item_wall = 1 and item_deleted = 0 and uid = %d and created > %s - INTERVAL %s and resource_type = '' order by created", intval($channel_id), db_utcnow(), @@ -1394,15 +1408,15 @@ function get_my_address() { } /** - * @brief + * @brief Add visitor's zid to our xchan and attempt authentication. * - * If somebody arrives at our site using a zid, add their xchan to our DB if we don't have it already. + * If somebody arrives at our site using a zid, add their xchan to our DB if we + * don't have it already. * And if they aren't already authenticated here, attempt reverse magic auth. * - * - * @hooks 'zid_init' - * string 'zid' - their zid - * string 'url' - the destination url + * @hooks zid_init + * * \e string \b zid - their zid + * * \e string \b url - the destination url */ function zid_init() { $tmp_str = get_my_address(); @@ -1431,12 +1445,9 @@ function zid_init() { } /** - * @brief - * - * If somebody arrives at our site using a zat, authenticate them + * @brief If somebody arrives at our site using a zat, authenticate them. * */ - function zat_init() { if(local_channel() || remote_channel()) return; @@ -1448,7 +1459,6 @@ function zat_init() { $xchan = atoken_xchan($r[0]); atoken_login($xchan); } - } @@ -1481,7 +1491,7 @@ function get_theme_uid() { * * @param int $size * one of (300, 80, 48) -* @returns string +* @returns string with path to profile photo */ function get_default_profile_photo($size = 300) { $scheme = get_config('system','default_profile_photo'); @@ -1974,7 +1984,6 @@ function channel_manual_conv_update($channel_id) { $x = get_config('system','manual_conversation_update', 1); return intval($x); - } @@ -2143,24 +2152,33 @@ function account_remove($account_id,$local = true,$unset_session=true) { } -function channel_remove($channel_id, $local = true, $unset_session=false) { +/** + * @brief Removes a channel. + * + * @hooks channel_remove + * * \e array \b entry from channel tabel for $channel_id + * @param int $channel_id + * @param boolean $local default true + * @param boolean $unset_session default false + */ +function channel_remove($channel_id, $local = true, $unset_session = false) { if(! $channel_id) return; logger('Removing channel: ' . $channel_id); - logger('channel_remove: local only: ' . intval($local)); + logger('local only: ' . intval($local)); $r = q("select * from channel where channel_id = %d limit 1", intval($channel_id)); if(! $r) { - logger('channel_remove: channel not found: ' . $channel_id); + logger('channel not found: ' . $channel_id); return; } $channel = $r[0]; - call_hooks('channel_remove',$r[0]); - + call_hooks('channel_remove', $r[0]); + if(! $local) { $r = q("update channel set channel_deleted = '%s', channel_removed = 1 where channel_id = %d", @@ -2173,12 +2191,11 @@ function channel_remove($channel_id, $local = true, $unset_session=false) { ); logger('deleting hublocs',LOGGER_DEBUG); - + $r = q("update hubloc set hubloc_deleted = 1 where hubloc_hash = '%s'", dbesc($channel['channel_hash']) ); - $r = q("update xchan set xchan_deleted = 1 where xchan_hash = '%s'", dbesc($channel['channel_hash']) ); @@ -2211,8 +2228,7 @@ function channel_remove($channel_id, $local = true, $unset_session=false) { q("DELETE FROM profile WHERE uid = %d", intval($channel_id)); q("DELETE FROM pconfig WHERE uid = %d", intval($channel_id)); - // @FIXME At this stage we need to remove the file resources located under /store/$nickname - + /// @FIXME At this stage we need to remove the file resources located under /store/$nickname q("delete from abook where abook_xchan = '%s' and abook_self = 1 ", dbesc($channel['channel_hash']) @@ -2263,16 +2279,16 @@ function channel_remove($channel_id, $local = true, $unset_session=false) { dbesc($channel['channel_hash']) ); } - + //remove from file system $r = q("select channel_address from channel where channel_id = %d limit 1", intval($channel_id) ); - + if($r) { $channel_address = $r[0]['channel_address'] ; } - if($channel_address) { + if($channel_address) { $f = 'store/' . $channel_address.'/'; logger('delete '. $f); if(is_dir($f)) { @@ -2286,22 +2302,24 @@ function channel_remove($channel_id, $local = true, $unset_session=false) { App::$session->nuke(); goaway(z_root()); } - } -/* - * This checks if a channel is allowed to publish executable code. - * It is up to the caller to determine if the observer or local_channel - * is in fact the resource owner whose channel_id is being checked +/** + * @brief This checks if a channel is allowed to publish executable code. + * + * It is up to the caller to determine if the observer or local_channel + * is in fact the resource owner whose channel_id is being checked. + * + * @param int $channel_id + * @return boolean */ - function channel_codeallowed($channel_id) { - if(! intval($channel_id)) return false; $x = channelx_by_n($channel_id); if(($x) && ($x['channel_pageflags'] & PAGE_ALLOWCODE)) return true; + return false; } diff --git a/include/feedutils.php b/include/feedutils.php index 06a342a3f..6bb7d103e 100644 --- a/include/feedutils.php +++ b/include/feedutils.php @@ -742,7 +742,7 @@ function encode_rel_links($links) { * @param $importer * The contact_record (joined to user_record) of the local user who owns this * relationship. It is this person's stuff that is going to be updated. - * @param array $contact[in,out] + * @param[in,out] array $contact * The person who is sending us stuff. If not set, we MAY be processing a "follow" activity * from an external network and MAY create an appropriate contact record. Otherwise, we MUST * have a contact record. @@ -1232,8 +1232,11 @@ function handle_feed($uid, $abook_id, $url) { /** * @brief Return a XML tag with author information. * + * @hooks \b atom_author Possibility to add further tags to returned XML string + * * \e string The created XML tag as a string without closing tag * @param string $tag The XML tag to create - * @param string $name Name of the author + * @param string $nick preferred username + * @param string $name displayed name of the author * @param string $uri * @param int $h image height * @param int $w image width diff --git a/include/import.php b/include/import.php index 224bb1803..3b5ddd1f1 100644 --- a/include/import.php +++ b/include/import.php @@ -181,7 +181,7 @@ function import_profiles($channel, $profiles) { * @param array $channel * @param array $hublocs * @param unknown $seize - * @param boolean $moving + * @param boolean $moving (optional) default false */ function import_hublocs($channel, $hublocs, $seize, $moving = false) { @@ -585,7 +585,7 @@ function sync_chatrooms($channel, $chatrooms) { * * @param array $channel where to import to * @param array $items - * @param boolean $sync + * @param boolean $sync default false * @param array $relocate default null */ function import_items($channel, $items, $sync = false, $relocate = null) { @@ -654,9 +654,13 @@ function sync_items($channel, $items, $relocate = null) { import_items($channel, $items, true, $relocate); } - - -function import_item_ids($channel,$itemids) { +/** + * @brief + * + * @param array $channel A channel array. + * @param array $itemids + */ +function import_item_ids($channel, $itemids) { if($channel && $itemids) { foreach($itemids as $i) { $r = q("select id from item where mid = '%s' and uid = %d limit 1", @@ -979,6 +983,7 @@ function import_conv($channel,$convs) { * * @param array $channel * @param array $mails + * @param boolean $sync (optional) default false */ function import_mail($channel, $mails, $sync = false) { if($channel && $mails) { @@ -1276,7 +1281,7 @@ function sync_files($channel, $files) { * * Replaces $old key with $new key in $arr. * - * @param array[in,out] $arr The array where to work on + * @param[in,out] array &$arr The array where to work on * @param string $old The old key in the array * @param string $new The new key in the array */ @@ -1444,7 +1449,7 @@ function import_webpage_element($element, $channel, $type) { // The author is either the owner or whomever was specified $arr['author_xchan'] = (($element['author_xchan']) ? $element['author_xchan'] : get_observer_hash()); // Import mimetype if it is a valid mimetype for the element - $mimetypes = [ + $mimetypes = [ 'text/bbcode', 'text/html', 'text/markdown', diff --git a/include/items.php b/include/items.php index c895a6d6e..4b90840e2 100755 --- a/include/items.php +++ b/include/items.php @@ -298,11 +298,13 @@ function add_source_route($iid, $hash) { * or other processing is performed. * * @param array $arr + * @param boolean $allow_code (optional) default false + * @param boolean $deliver (optional) default true * @returns array * * \e boolean \b success true or false * * \e array \b activity the resulting activity if successful */ -function post_activity_item($arr,$allow_code = false,$deliver = true) { +function post_activity_item($arr, $allow_code = false, $deliver = true) { $ret = array('success' => false); @@ -348,7 +350,7 @@ function post_activity_item($arr,$allow_code = false,$deliver = true) { if(($is_comment) && ($arr['obj_type'] === ACTIVITY_OBJ_NOTE)) $arr['obj_type'] = ACTIVITY_OBJ_COMMENT; - if(! ( array_key_exists('allow_cid',$arr) || array_key_exists('allow_gid',$arr) + if(! ( array_key_exists('allow_cid',$arr) || array_key_exists('allow_gid',$arr) || array_key_exists('deny_cid',$arr) || array_key_exists('deny_gid',$arr))) { $arr['allow_cid'] = $channel['channel_allow_cid']; $arr['allow_gid'] = $channel['channel_allow_gid']; @@ -648,11 +650,11 @@ function get_item_elements($x,$allow_code = false) { } } - // Check signature on the body text received. + // Check signature on the body text received. // This presents an issue that we aren't verifying the text that is actually displayed // on this site. We are however verifying the received text was exactly as received. // We have every right to strip content that poses a security risk. You are welcome to - // create a plugin to verify the content after filtering if this offends you. + // create a plugin to verify the content after filtering if this offends you. if($arr['sig']) { @@ -675,7 +677,7 @@ function get_item_elements($x,$allow_code = false) { // If we don't have a public key, strip the signature so it won't show as invalid. // This won't happen in normal use, but could happen if import_author_xchan() - // failed to load the zot-info packet due to a server failure and had + // failed to load the zot-info packet due to a server failure and had // to create an alternate xchan with network 'unknown' unset($arr['sig']); @@ -1518,7 +1520,7 @@ function item_store($arr, $allow_exec = false, $deliver = true) { if(array_key_exists('cancel',$arr) && $arr['cancel']) { logger('cancelled by plugin'); return $ret; - } + } if(! $arr['uid']) { logger('item_store: no uid'); @@ -1843,7 +1845,7 @@ logger('revision: ' . $arr['revision']); ); if($r) { - // This will gives us a fresh copy of what's now in the DB and undo the db escaping, + // This will gives us a fresh copy of what's now in the DB and undo the db escaping, // which really messes up the notifications $current_post = $r[0]['id']; @@ -1906,7 +1908,7 @@ logger('revision: ' . $arr['revision']); // update the commented timestamp on the parent - unless this is potentially a clone of an older item // which we don't wish to bring to the surface. As the queue only holds deliveries for 3 days, it's - // suspected of being an older cloned item if the creation time is older than that. + // suspected of being an older cloned item if the creation time is older than that. if($arr['created'] > datetime_convert('','','now - 4 days')) { $z = q("select max(created) as commented from item where parent_mid = '%s' and uid = %d and item_delayed = 0 ", @@ -1952,7 +1954,7 @@ function item_store_update($arr,$allow_exec = false, $deliver = true) { if(array_key_exists('cancel',$arr) && $arr['cancel']) { logger('cancelled by plugin'); return $ret; - } + } if(! intval($arr['uid'])) { logger('item_store_update: no uid'); @@ -4502,12 +4504,12 @@ function item_create_edit_activity($post) { $new_item['id'] = 0; $new_item['parent'] = 0; $new_item['mid'] = item_message_id(); - + $new_item['body'] = sprintf( t('[Edited %s]'), (($update_item['item_thread_top']) ? t('Post','edit_activity') : t('Comment','edit_activity'))); $new_item['body'] .= "\n\n"; $new_item['body'] .= $update_item['body']; - + $new_item['sig'] = ''; $new_item['verb'] = ACTIVITY_UPDATE; @@ -4533,10 +4535,10 @@ function item_create_edit_activity($post) { array('rel' => 'photo', 'type' => $item_author['xchan_photo_mimetype'], 'href' => $item_author['xchan_photo_m'])), ), )); - - $x = post_activity_item($new_item); + + $x = post_activity_item($new_item); $post_id = $x['id']; if($post_id) { @@ -4551,5 +4553,5 @@ function item_create_edit_activity($post) { } \Zotlabs\Daemon\Master::Summon(array('Notifier', 'edit_activity', $post_id)); - + } diff --git a/include/text.php b/include/text.php index 46509aabf..162d7c365 100644 --- a/include/text.php +++ b/include/text.php @@ -774,9 +774,9 @@ function activity_match($haystack,$needle) { } /** - * @brief Pull out all #hashtags and @person tags from $s. + * @brief Pull out all \#hashtags and \@person tags from $s. * - * We also get @person@domain.com - which would make + * We also get \@person\@domain.com - which would make * the regex quite complicated as tags can also * end a sentence. So we'll run through our results * and strip the period from any tags which end with one. @@ -2079,7 +2079,7 @@ function ids_to_querystr($arr,$idx = 'id',$quote = false) { * If $abook is true also include the abook info. This is needed in the API to * save extra per item lookups there. * - * @param array[in,out] &$items + * @param[in,out] array &$items * @param boolean $abook If true also include the abook info * @param number $effective_uid */ @@ -2175,10 +2175,10 @@ function magic_link($s) { } /** - * if $escape is true, dbesc() each element before adding quotes + * @brief If $escape is true, dbesc() each element before adding quotes. * - * @param array[in,out] &$arr - * @param boolean $escape default false + * @param[in,out] array &$arr + * @param boolean $escape (optional) default false */ function stringify_array_elms(&$arr, $escape = false) { for($x = 0; $x < count($arr); $x ++) @@ -2189,7 +2189,6 @@ function stringify_array_elms(&$arr, $escape = false) { * @brief Indents a flat JSON string to make it more human-readable. * * @param string $json The original JSON string to process. - * * @return string Indented version of the original JSON string. */ function jindent($json) { @@ -3140,4 +3139,4 @@ function ellipsify($s,$maxlen) { return $s; return mb_substr($s,0,$maxlen / 2) . '...' . mb_substr($s,mb_strlen($s) - ($maxlen / 2)); -} +} -- cgit v1.2.3