services_docs.module

<?php

/**
 * @file
 *   Generates user-friendly documentation for the services available on the site.
 */

/**
 * Implementation of hook_perm().
 */
function services_docs_perm() {
  return array('access services documentation');
}

/**
 * Implementation of hook_menu().
 */
function services_docs_menu() {
  $items = array();

  $items['services-docs'] = array(
    'title' => 'Services documentation',
    'page callback' => 'services_docs_page_all',
    'access arguments' => array('access services documentation'),
    'type' => MENU_NORMAL_ITEM,
  );
  $items['services-docs/%services_method'] = array(
    'title' => 'Services documentation',
    'page callback' => 'services_docs_page_method',
    'page arguments' => array(1),
    'access arguments' => array('access services documentation'),
    'type' => MENU_CALLBACK,
  );

  return $items;
}

/**
 * Page callback.
 *
 * Much of this is taken from services_admin_browse_index()
 */
function services_docs_page_all() {
  $methods = services_get_all();

  // Show enabled server modules
  $servers = module_implements('server_info');
  $output = '<h2>'. t('Servers') .'</h2>';

  if (!empty($servers)) {
    $output .= '<ul>';
    foreach ($servers as $module) {
      $info = module_invoke($module, 'server_info');
      services_strip_hashes($info);

      $name = $info['name'];
      $path = 'services/'. $info['path'];
      $output .= '<li class="leaf">'. l($name .' - /'. $path, $path) .'</li>';
    }
    $output .= '</ul>';
  }
  else {
    $output .= '<p>' .t('No servers have been enabled') .'</p>';
  }

  // Show services
  $output .= '<h2>'. t('Services') .'</h2>';

  // group namespaces
  $services = array();
  foreach ($methods as $method) {
    $namespace = drupal_substr($method['method'], 0, strrpos($method['method'], '.'));
    $services[$namespace][] = $method;
  }

  if (count($services)) {
    foreach ($services as $namespace => $methods) {
      $output .= '<h3>'. $namespace .'</h3>';
      $output .= '<ul>';
      foreach ($methods as $method) {
        $output .= '<li class="leaf">'. l($method['method'], 'services-docs/'. $method['method']) .'</li>';
      }
      $output .= '</ul>';
    }
  }
  else {
    $output .= t('No services have been enabled.');
  }

  return $output;
}

/**
 * Page callback.
 *
 * Render docs for an individual method.
 * @todo Show roles w/ permission to view
 */
function services_docs_page_method($method) {
  drupal_set_title(t('Service') .': '. check_plain($method['method']));
  $output = '';

  $output .= '<p>'. $method['help'] .'</p>';

  // Show a sample
  $args = array();
  foreach ($method['args'] as $arg) {
    $args[] = $arg['type'] .' <em>$'. $arg['name'] .'</em>';
  }
  $output .= '<p><strong>'. $method['method'] .'</strong>( '. implode(' , ', $args) .' )</p>';

  // List arguments
  $output .= '<h3>'. t('Arguments') .' ('. count($method['args']) .')</h3>';
  $output .= '<dl id="service-browser-arguments">';
  $count = 0;
  foreach ($method['args'] as $arg) {
    $count++;
    $output .= '<dt><em class="type">'. $arg['type'] .'</em> <strong class="name">'.
      $arg['name'] .'</strong> ('. (($arg['optional']) ? t('optional') : t('required')) .')</dt>';
    $output .= '<dd>'. $arg['description'] .'</dd>';
  }

  $output .= '</dl>';

  // Return
  $output .= '<h3>'. t('Returns') .'</h3>';
  $output .= '<p>'. $method['return'] .'</p>';

  return $output;
}