Revise API reference templates to make them compatible

with both DAC and DevSite. Includes a variety of cleanup and redesign. Now prints method parameters and return values even if not documented in source. Now prints return value data type. Now prints method name as heading without arguments, then the full signature below. New heading styles with more spacing and removed background color. Change-Id: I7a991df5e8d0d7ac8ff81c20b4b4692e67eb88aa
2016-02-05 17:34:22 -08:00
parent 01c63ddc2b
commit a0a6d3220f
10 changed files with 613 additions and 562 deletions
--- a/tools/droiddoc/templates-sdk-dev/assets/css/default.css
+++ b/tools/droiddoc/templates-sdk-dev/assets/css/default.css
@@ -224,6 +224,14 @@ h5, h6 {
  margin: 0;
  padding: 4px 0 8px;
 }
+th>h3 {
+  font-size:inherit;
+  line-height:inherit;
+  font-weight:inherit;
+  margin:0;
+  padding:0;
+  color:inherit;
+}
 hr { /* applied to the bottom of h2 elements */
  height: 1px;
  margin: 7px 0 12px;
@@ -291,11 +299,6 @@ pre, code {
  -webkit-font-smoothing: subpixel-antialiased;
  -moz-osx-font-smoothing: auto;
 }
-code {
-  background-color: #f7f7f7;
-  padding: 3px 5px;
-}
-
 legend {
  display: none;
 }
@@ -1680,6 +1683,46 @@ pre {
  border: solid 1px #ddd;
  background: #f7f7f7;
 }
+
+p.package-name {
+  margin:1em 0;
+}
+
+h1.api-title {
+  padding-bottom:0;
+}
+
+h2.api-section {
+  margin: 60px 0 0;
+}
+
+h2.api-section+hr {
+  margin-bottom: 30px;
+}
+
+h3.api-name {
+  margin: 80px 0 12px;
+  padding: 0;
+}
+
+/* remove top padding when this h3 (visibly) follows an h2.
+   This accounts for the variation in structure,
+   including the collapsed mobile headings */
+h2+hr+div>div>a+div>h3.api-name,
+h2+hr+a+div>h3.api-name,
+h2+hr+a+h3.api-name {
+  margin-top: 0;
+}
+
+pre.api-signature,
+code.api-signature {
+  color:inherit;
+  padding:0;
+  margin:1em 0;
+  border:0;
+  background:transparent;
+}
+
 .str { color: #800; } /* Code string */
 .kwd { color: #008; }
 .typ { color: #606; }
@@ -2612,7 +2655,7 @@ div#naMessage div {
  z-index:99;
  width:450px;
  position:fixed;
-  margin:50px 0;
+  margin:80px 0;
  padding:4em 4em 3em;
  background:#FFF;
  border:1px solid #999;
@@ -2877,19 +2920,6 @@ Page-Specific Styles
  padding:0 0 0 4px;
 }

-#jd-header {
-  padding: 0 0 12px;
-  margin: 20px 0 12px;
-  font-size:12px;
-  padding-bottom:12px;
-  border-bottom:solid 1px #ccc;
-}
-
-#jd-header h1 {
-  margin:0;
-  padding:0 0 6px 0;
-}
-
 /* not sure if this is needed in the ref docs, disabling for now
 .jd-descr h2 {
  margin:16px 0;
@@ -2910,12 +2940,11 @@ links to summary tables) */
 #api-info-block {
  font-size:12px;
  margin:20px 0 0;
-  padding:0 10px 6px;
  font-weight:normal;
  float:right;
  text-align:right;
  color:#999;
-  max-width:80%;
+  max-width:300px;
  font-size: 12px;
  line-height:14px;
 }
@@ -2930,12 +2959,17 @@ links to summary tables) */
 }

 /* inheritance table */
+table.inhtable>tbody>tr>td {
+  padding-left:0;
+}
+table.inhtable>tbody>tr>td div:first-of-type {
+  padding-left:12px;
+}
+
 .jd-inheritance-table {
  border-spacing:0;
-  margin:0;
+  margin:1em 0;
  padding:0;
-  font-size:12px;
-  line-height:14px;
  background-color:transparent;
 }
 .jd-inheritance-table tr td {
@@ -2945,23 +2979,13 @@ links to summary tables) */
  background-color:transparent;
 }
 .jd-inheritance-table .jd-inheritance-space {
-  font-weight:bold;
-  width:1em;
+  width:2em;
 }
 .jd-inheritance-table .jd-inheritance-interface-cell {
  padding-left: 17px;
 }


-
-.jd-sumtable a {
-  text-decoration:none;
-}
-
-.jd-sumtable a:hover {
-  text-decoration:underline;
-}
-
 /* the link inside a sumtable for "Show All/Hide All" */
 .toggle-all {
  display:block;
@@ -2971,11 +2995,10 @@ links to summary tables) */
 }

 /* adjustments for in/direct subclasses tables */
-.jd-sumtable.jd-sumtable-subclasses {
+.jd-sumtable-subclasses {
  margin: 1em 0 0 0;
  max-width:968px;
  background-color:transparent;
-  font-size:13px;
 }

 /* extra space between end of method name and open-paren */
@@ -2983,11 +3006,6 @@ links to summary tables) */
  margin-right: 2px;
 }

-/* right alignment for the return type in sumtable */
-.jd-sumtable .jd-typecol {
-  text-align:right;
-}
-
 /* adjustments for the expando table-in-table */
 .jd-sumtable-expando {
  margin:.5em 0;
@@ -3008,7 +3026,9 @@ links to summary tables) */

 .jd-sumtable-subclasses div#subclasses-direct,
 .jd-sumtable-subclasses div#subclasses-indirect {
-  margin:0 0 0 13px;
+  /* left margin matches width of the toggle image,
+     so this section aligns with the text above */
+  margin:0 0 0 34px;
 }


@@ -3077,10 +3097,6 @@ body.google h4.jd-details-title {
  padding-top:5px;
  border-top: 1px solid #ccc;
 }
-body.google table.jd-sumtable th {
-  background-color: #FFF;
-  color:#000;
-}

 h4.jd-tagtitle {
  padding:0;
@@ -3124,7 +3140,7 @@ div.api-level {
  color:#999;
  float:right;
  padding:0 8px 0;
-  margin-top:-30px;
+  margin-top:-35px;
 }

 table.jd-tagtable td,
--- a/tools/droiddoc/templates-sdk-dev/assets/js/docs.js
+++ b/tools/droiddoc/templates-sdk-dev/assets/js/docs.js
@@ -875,8 +875,7 @@ function changeApiLevel() {
  writeCookie(API_LEVEL_COOKIE, selectedLevel, null);

  if (selectedLevel < minLevel) {
-    var thing = ($("#jd-header").html().indexOf("package") != -1) ? "package" : "class";
-    $("#naMessage").show().html("<div><p><strong>This " + thing +
+    $("#naMessage").show().html("<div><p><strong>This API" +
              " requires API level " + minLevel + " or higher.</strong></p>" +
              "<p>This document is hidden because your selected API level for the documentation is " +
              selectedLevel + ". You can change the documentation API level with the selector " +
@@ -1104,13 +1103,13 @@ function toggleInherited(linkObj, expand) {
  if ((expand == null && a.hasClass("closed")) || expand) {
    list.style.display = "none";
    summary.style.display = "block";
-    trigger.src = toRoot + "assets/images/triangle-opened.png";
+    trigger.src = toRoot + "assets/images/styles/disclosure_up.png";
    a.removeClass("closed");
    a.addClass("opened");
  } else if ((expand == null && a.hasClass("opened")) || (expand == false)) {
    list.style.display = "block";
    summary.style.display = "none";
-    trigger.src = toRoot + "assets/images/triangle-closed.png";
+    trigger.src = toRoot + "assets/images/styles/disclosure_down.png";
    a.removeClass("opened");
    a.addClass("closed");
  }
@@ -4379,9 +4378,9 @@ $.fn.scrollIntoView = function(target) {
        selected = navEl.find('> li.guides > a').addClass('selected');
      } else if (body.hasClass('reference')) {
        selected = navEl.find('> li.reference > a').addClass('selected');
-      } else if (body.hasClass('samples')) { 
+      } else if (body.hasClass('samples')) {
        selected = navEl.find('> li.samples > a').addClass('selected');
-      } else if (body.hasClass('downloads')) { 
+      } else if (body.hasClass('downloads')) {
        selected = navEl.find('> li.downloads > a').addClass('selected');
      }
    } else if (body.hasClass('design')) {
@@ -4986,7 +4985,7 @@ window.metadata.search = (function() {
      var noBoundaries = (NO_BOUNDARY_LANGUAGES.indexOf(window.getLangPref()) !== -1);
      var exprBoundary = (!isAsciiOnly && noBoundaries) ? '' : '(?:^|\\s)';
      var queryRegex = new RegExp(exprBoundary + query.toLowerCase(), 'g');
-        
+
      var all = METADATA.all;
      for (var i = 0; i < all.length; i++) {
        // current search comparison, with counters for tag and title,
--- a/tools/droiddoc/templates-sdk-dev/body_tag.cs
+++ b/tools/droiddoc/templates-sdk-dev/body_tag.cs
@@ -0,0 +1,15 @@
+<body class="gc-documentation <?cs
+  if:(reference.gms || reference.gcm)
+    ?>google<?cs
+  /if ?><?cs
+  if:(guide||develop||training||reference||tools||sdk)
+    ?>develop<?cs
+    if:reference
+      ?> reference api apilevel-<?cs var:class.since ?><?cs var:package.since ?><?cs
+    /if ?><?cs
+  elif:design
+    ?>design<?cs
+  elif:distribute
+    ?>distribute<?cs
+  /if ?>">
+<div id="doc-api-level" class="<?cs var:class.since ?><?cs var:package.since ?>" style="display:none"></div>
--- a/tools/droiddoc/templates-sdk-dev/class.cs
+++ b/tools/droiddoc/templates-sdk-dev/class.cs
--- a/tools/droiddoc/templates-sdk-dev/classes.cs
+++ b/tools/droiddoc/templates-sdk-dev/classes.cs
@@ -1,32 +1,27 @@
-<?cs include:"doctype.cs" ?>
+<?cs # THIS CREATES A LIST OF ALL PACKAGES AND NAMES IT packages.html ?>
 <?cs include:"macros.cs" ?>
 <?cs include:"macros_override.cs" ?>
+<?cs include:"doctype.cs" ?>
 <html<?cs if:devsite ?> devsite<?cs /if ?>>
 <?cs include:"head_tag.cs" ?>
-<body class="gc-documentation <?cs if:(reference.gms || reference.gcm) ?>google<?cs /if ?>
-  <?cs if:(guide||develop||training||reference||tools||sdk) ?>develop<?cs
-    if:reference ?> reference<?cs
-    /if ?><?cs
-  elif:design ?>design<?cs
-  elif:distribute ?>distribute<?cs
-  /if ?>" itemscope itemtype="http://schema.org/Article">
-  <a name="top"></a>
+<?cs include:"body_tag.cs" ?>
 <?cs include:"header.cs" ?>

-<div id="jd-header">
 <h1><?cs var:page.title ?></h1>
-</div>
+<p>These are the API classes. See all
+<a href="packages.html">API packages</a>.</p>

-<div id="jd-content">
-<p>These are the Android API classes. See all <a href="packages.html">API packages</a>.</p>
-<div class="jd-letterlist"><?cs each:letter=docs.classes ?>
-    <a href="#letter_<?cs name:letter ?>"><?cs name:letter ?></a>&nbsp;&nbsp;<?cs /each?>
+<div class="jd-letterlist"><?cs
+  each:letter=docs.classes ?>
+    <a href="#letter_<?cs name:letter ?>"><?cs
+      name:letter ?></a>&nbsp;&nbsp;<?cs
+  /each?>
 </div>

 <?cs each:letter=docs.classes ?>
 <?cs set:count = #1 ?>
 <h2 id="letter_<?cs name:letter ?>"><?cs name:letter ?></h2>
-<table class="jd-sumtable">
+<table>
    <?cs set:cur_row = #0 ?>
    <?cs each:cl = letter ?>
        <tr class="<?cs if:count % #2 ?>alt-color<?cs /if ?> api apilevel-<?cs var:cl.since ?>" >
@@ -41,11 +36,7 @@
 </table>
 <?cs /each ?>

-</div><!-- end jd-content -->
-
 <?cs include:"footer.cs" ?>
-
 <?cs include:"trailer.cs" ?>
-
 </body>
 </html>
--- a/tools/droiddoc/templates-sdk-dev/footer.cs
+++ b/tools/droiddoc/templates-sdk-dev/footer.cs
@@ -1,3 +1,4 @@
+<?cs # page footer content ?>
 <div class="wrap">
  <div class="dac-footer<?cs if:fullpage ?> dac-landing<?cs /if ?>">
    <div class="cols dac-footer-main">
--- a/tools/droiddoc/templates-sdk-dev/package.cs
+++ b/tools/droiddoc/templates-sdk-dev/package.cs
@@ -1,48 +1,25 @@
-<?cs include:"doctype.cs" ?>
+<?cs # THIS CREATES A PACKAGE SUMMARY PAGE FROM EACH package.html FILES
+     # AND NAMES IT package-summary.html ?>
 <?cs include:"macros.cs" ?>
 <?cs include:"macros_override.cs" ?>
+<?cs include:"doctype.cs" ?>
 <html<?cs if:devsite ?> devsite<?cs /if ?>>
 <?cs include:"head_tag.cs" ?>
-
-<body class="gc-documentation <?cs if:(reference.gms || reference.gcm) ?>google<?cs /if ?>
-  <?cs if:(guide||develop||training||reference||tools||sdk) ?>develop<?cs
-    if:reference ?> reference<?cs
-    /if ?><?cs
-  elif:design ?>design<?cs
-  elif:distribute ?>distribute<?cs
-  /if ?>">
-  <div id="doc-api-level" class="<?cs var:package.since ?>" style="display:none"></div>
-  <a name="top"></a>
+<?cs include:"body_tag.cs" ?>
 <?cs include:"header.cs" ?>
+<?cs include:"page_info.cs" ?>
+<div class="api apilevel-<?cs var:package.since ?>" id="jd-content">

-<div id="api-info-block">
-<div class="api-level">
-  <?cs call:since_tags(package) ?>
-  <?cs call:federated_refs(package) ?>
-</div>
-</div>
-
-<div id="jd-header">
-  package
-  <h1><?cs var:package.name ?></h1>
-</div><!-- end header -->
-
-<div id="naMessage"></div>
-
-<div id="jd-content" class="api apilevel-<?cs var:package.since ?>">
+<h1><?cs var:package.name ?></h1>

 <?cs if:subcount(package.descr) ?>
-  <div class="jd-descr">
-    <?cs call:tag_list(package.descr) ?>
-  </div>
+  <?cs call:tag_list(package.descr) ?>
 <?cs /if ?>

 <?cs def:class_table(label, classes) ?>
  <?cs if:subcount(classes) ?>
    <h2><?cs var:label ?></h2>
-    <div class="jd-sumtable">
    <?cs call:class_link_table(classes) ?>
-    </div>
  <?cs /if ?>
 <?cs /def ?>

@@ -53,11 +30,8 @@
 <?cs call:class_table("Exceptions", package.exceptions) ?>
 <?cs call:class_table("Errors", package.errors) ?>

-</div><!-- end jd-content -->
-
+</div><!-- end apilevel -->
 <?cs include:"footer.cs" ?>
-
 <?cs include:"trailer.cs" ?>
-
 </body>
 </html>
--- a/tools/droiddoc/templates-sdk-dev/packages.cs
+++ b/tools/droiddoc/templates-sdk-dev/packages.cs
@@ -1,31 +1,19 @@
-<?cs include:"doctype.cs" ?>
+<?cs # THIS CREATES A LIST OF ALL PACKAGES AND NAMES IT packages.html ?>
 <?cs include:"macros.cs" ?>
+<?cs include:"doctype.cs" ?>
 <html<?cs if:devsite ?> devsite<?cs /if ?>>
 <?cs include:"head_tag.cs" ?>
-<body class="gc-documentation <?cs if:(reference.gms || reference.gcm) ?>google<?cs /if ?>
-  <?cs if:(guide||develop||training||reference||tools||sdk) ?>develop<?cs
-    if:reference ?> reference<?cs
-    /if ?><?cs
-  elif:design ?>design<?cs
-  elif:distribute ?>distribute<?cs
-  /if ?>">
-  <a name="top"></a>
+<?cs include:"body_tag.cs" ?>
 <?cs include:"header.cs" ?>

-<div id="jd-header">
 <h1><?cs var:page.title ?></h1>
-</div>
-
-<div id="jd-content">
-
-<div class="jd-descr">
-<p><?cs call:tag_list(root.descr) ?></p>
-</div>
+<p>These are the API packages.
+See all <a href="classes.html">API classes</a>.</p>

 <?cs set:count = #1 ?>
-<table class="jd-sumtable">
+<table>
 <?cs each:pkg = docs.packages ?>
-    <tr class="<?cs if:count % #2 ?>alt-color<?cs /if ?> api apilevel-<?cs var:pkg.since ?>" >
+    <tr class="api apilevel-<?cs var:pkg.since ?>" >
        <td class="jd-linkcol"><?cs call:package_link(pkg) ?></td>
        <td class="jd-descrcol" width="100%"><?cs call:tag_list(pkg.shortDescr) ?></td>
    </tr>
@@ -33,11 +21,7 @@
 <?cs /each ?>
 </table>

-</div><!-- end jd-content -->
-
 <?cs include:"footer.cs" ?>
-
 <?cs include:"trailer.cs" ?>
-
 </body>
 </html>
--- a/tools/droiddoc/templates-sdk-dev/page_info.cs
+++ b/tools/droiddoc/templates-sdk-dev/page_info.cs
@@ -0,0 +1,109 @@
+<?cs # optional, more info about the page, such as API level and links ?>
+<?cs
+# A modal dialog when API level is set too low for this page
+?><div id="naMessage"></div>
+<?cs
+#
+# If this is a package summary page...
+#
+?><?cs
+if:subcount(package)
+?>
+<div id="api-info-block">
+<div class="api-level">
+  <?cs call:since_tags(package) ?>
+  <?cs call:federated_refs(package) ?>
+</div>
+</div><?cs
+#
+# Or if this is a class page...
+#
+?><?cs
+elif:subcount(class)
+?>
+<div id="api-info-block">
+<div class="api-level">
+  <?cs call:since_tags(class) ?><?cs
+  if:class.deprecatedsince
+    ?><br>Deprecated since <a href="<?cs var:toroot ?>guide/topics/manifest/uses-sdk-element.html#ApiLevels"
+        >API level <?cs var:class.deprecatedsince ?></a><?cs
+  /if ?>
+  <?cs call:federated_refs(class) ?>
+</div>
+
+<?cs # Set variables about whether there are inherited members; no output ?>
+<?cs each:cl=class.inherited ?>
+  <?cs if:subcount(cl.methods) ?>
+   <?cs set:inhmethods = #1 ?>
+  <?cs /if ?>
+  <?cs if:subcount(cl.constants) ?>
+   <?cs set:inhconstants = #1 ?>
+  <?cs /if ?>
+  <?cs if:subcount(cl.fields) ?>
+   <?cs set:inhfields = #1 ?>
+  <?cs /if ?>
+  <?cs if:subcount(cl.attrs) ?>
+   <?cs set:inhattrs = #1 ?>
+  <?cs /if ?>
+<?cs /each ?>
+
+<div class="sum-details-links">
+<?cs if:inhattrs || inhconstants || inhfields || inhmethods || (!class.subclasses.hidden &&
+     (subcount(class.subclasses.direct) || subcount(class.subclasses.indirect))) ?>
+Summary:
+<?cs if:subcount(class.inners) ?>
+  <a href="#nestedclasses">Nested Classes</a>
+  <?cs set:linkcount = #1 ?>
+<?cs /if ?>
+<?cs if:subcount(class.attrs) ?>
+  <?cs if:linkcount ?>&#124; <?cs /if ?><a href="#lattrs">XML Attrs</a>
+  <?cs set:linkcount = #1 ?>
+<?cs /if ?>
+<?cs if:inhattrs ?>
+  <?cs if:linkcount ?>&#124; <?cs /if ?><a href="#inhattrs">Inherited XML Attrs</a>
+  <?cs set:linkcount = #1 ?>
+<?cs /if ?>
+<?cs if:subcount(class.enumConstants) ?>
+  <?cs if:linkcount ?>&#124; <?cs /if ?><a href="#enumconstants">Enums</a>
+  <?cs set:linkcount = #1 ?>
+<?cs /if ?>
+<?cs if:subcount(class.constants) ?>
+  <?cs if:linkcount ?>&#124; <?cs /if ?><a href="#constants">Constants</a>
+  <?cs set:linkcount = #1 ?>
+<?cs /if ?>
+<?cs if:inhconstants ?>
+  <?cs if:linkcount ?>&#124; <?cs /if ?><a href="#inhconstants">Inherited Constants</a>
+  <?cs set:linkcount = #1 ?>
+<?cs /if ?>
+<?cs if:subcount(class.fields) ?>
+  <?cs if:linkcount ?>&#124; <?cs /if ?><a href="#lfields">Fields</a>
+  <?cs set:linkcount = #1 ?>
+<?cs /if ?>
+<?cs if:inhfields ?>
+  <?cs if:linkcount ?>&#124; <?cs /if ?><a href="#inhfields">Inherited Fields</a>
+  <?cs set:linkcount = #1 ?>
+<?cs /if ?>
+<?cs if:subcount(class.ctors.public) ?>
+  <?cs if:linkcount ?>&#124; <?cs /if ?><a href="#pubctors">Ctors</a>
+  <?cs set:linkcount = #1 ?>
+<?cs /if ?>
+<?cs if:subcount(class.ctors.protected) ?>
+  <?cs if:linkcount ?>&#124; <?cs /if ?><a href="#proctors">Protected Ctors</a>
+  <?cs set:linkcount = #1 ?>
+<?cs /if ?>
+<?cs if:subcount(class.methods.public) ?>
+  <?cs if:linkcount ?>&#124; <?cs /if ?><a href="#pubmethods">Methods</a>
+  <?cs set:linkcount = #1 ?>
+<?cs /if ?>
+<?cs if:subcount(class.methods.protected) ?>
+  <?cs if:linkcount ?>&#124; <?cs /if ?><a href="#promethods">Protected Methods</a>
+  <?cs set:linkcount = #1 ?>
+<?cs /if ?>
+<?cs if:inhmethods ?>
+  <?cs if:linkcount ?>&#124; <?cs /if ?><a href="#inhmethods">Inherited Methods</a>
+<?cs /if ?>
+&#124; <a href="#" onclick="return toggleAllClassInherited()" id="toggleAllClassInherited">[Expand All]</a>
+<?cs /if ?>
+</div><!-- end sum-details-links -->
+</div><!-- end api-info-block --><?cs
+/if ?><?cs # end of if package or class ?>
--- a/tools/droiddoc/templates-sdk-dev/trailer.cs
+++ b/tools/droiddoc/templates-sdk-dev/trailer.cs
@@ -1,3 +1,7 @@
+<?cs
+# Other, non-visible things needed at the end of the page,
+# because not every page needs footer content, but does need other stuff
+?>
 </div> <!-- end body-content --> <?cs # normally opened by header.cs ?>

 <?cs if:carousel ?>