/dev/api: Add an overview section and explain fullnames.

r2/r2/lib/validator/validator.py

@@ -707,7 +707,7 @@ class VByName(Validator):
     def param_docs(self):
         thingtype = (self.thing_cls or Thing).__name__.lower()
         return {
-            self.param: "fullname of a %s" % thingtype,
+            self.param: "[fullname](#fullnames) of a %s" % thingtype,
         }
 
 class VByNameIfAuthor(VByName):
@@ -721,7 +721,7 @@ class VByNameIfAuthor(VByName):
 
     def param_docs(self):
         return {
-            self.param: "fullname of a thing created by the user",
+            self.param: "[fullname](#fullnames) of a thing created by the user",
         }
 
 class VCaptcha(Validator):
@@ -972,7 +972,7 @@ class VSubmitParent(VByName):
 
     def param_docs(self):
         return {
-            self.param[0]: "fullname of parent thing",
+            self.param[0]: "[fullname](#fullnames) of parent thing",
         }
 
 class VSubmitSR(Validator):

r2/r2/public/static/css/reddit.less

@@ -5975,6 +5975,18 @@ body:not(.gold) .allminus-link {
     top: 58px;
 }
 
+.api-help .contents .overview {
+    p {
+        margin: .8em 0;
+    }
+
+    code {
+        background-color: #f0f0f0;
+        padding: 0 .5em;
+        border-radius: 3px;
+    }
+}
+
 .api-help .toc ul {
     position: relative;
     margin-top: .5em;
@@ -6080,6 +6092,7 @@ body:not(.gold) .allminus-link {
     border-radius: 2px;
 }
 
+.api-help .overview h2,
 .api-help .methods h2 {
     color: black;
     font-size: 1.45em;
@@ -6144,6 +6157,11 @@ body:not(.gold) .allminus-link {
     width: 100%;
 }
 
+.api-help caption {
+    font-weight: bold;
+    margin: 1em 0 .5em .5em;
+}
+
 .api-help .parameters th,
 .api-help .parameters td {
     vertical-align: top;

r2/r2/templates/apihelp.html

@@ -25,6 +25,7 @@
     from r2.lib.filters import safemarkdown
     from r2.controllers.api_docs import section_info
     from r2.models.token import OAuth2Scope
+    from r2.lib.db.thing import thing_types
 %>
 
 <%def name="api_method_id(uri, method)">${method}_${uri.replace('/', '_').strip('_')}</%def>
@@ -128,6 +129,30 @@
     <p><strong>Please take care to respect our&#32;<a href="https://github.com/reddit/reddit/wiki/API">API access rules</a>.</strong></p>
   </div>
 
+  <div class="section overview">
+    <h2>overview</h2>
+
+    <h3 id="fullnames">fullnames</h3>
+
+    <p>A fullname is a combination of a thing's type
+    (e.g.&#32;<code>Link</code>) and its unique ID which forms a compact
+    encoding of a globally unique ID on reddit.</p>
+
+    <p>Fullnames start with the type prefix for the object's type, followed by
+    the thing's unique ID in&#32;<a href="http://en.wikipedia.org/wiki/Base36">base
+      36</a>. For example,&#32;<code>t3_15bfi0</code>.</p>
+
+    <table class="parameters">
+      <caption>type prefixes</caption>
+      % for typeid in sorted(thing_types):
+      <tr>
+        <th scope="row">t${typeid}_</th>
+        <td>${thing_types[typeid].__name__}</td>
+      </tr>
+      % endfor
+    </table>
+  </div>
+
   <div class="section methods">
     %for section in sorted(api):
       %if thing.mode == 'oauth':
@@ -187,7 +212,7 @@
                   %for param in sorted(params):
                     <tr>
                       <th scope="row">${param}</th>
-                      <td>${params[param]}</td>
+                      <td>${unsafe(safemarkdown(params[param], wrap=False))}</td>
                     </tr>
                   %endfor
                 %endif
@@ -195,7 +220,7 @@
                   %for param in sorted(base_params):
                     <tr class="base-param">
                       <th scope="row">${param}</th>
-                      <td>${base_params[param]}</td>
+                      <td>${unsafe(safemarkdown(base_params[param], wrap=False))}</td>
                     </tr>
                   %endfor
                 %endif