Make Exceptions a sub-grouping inside modules (#1124)

Author: archdragon

assets/js/autocomplete/suggestions.js

@@ -21,7 +21,7 @@ const labels = {
 }
 
 /**
- * Transform an object containing data about a search result and transforms it into a simple
+ * Takes an object containing data about a search result and transforms it into a simple
  * data structure that can be used directly in the autocomplete template.
  *
  * @param {Object} item Result to be serialized
@@ -44,7 +44,7 @@ function serialize (item, moduleId = null) {
     label: label, // 'Callback' or 'Type' - if set it will be displayed next to the title.
     matchQuality: item.matchQuality, // 0..1 - How well result matches the search term. Higher is better.
     category: category
-    // 'Module', 'Mix Task', 'Exception' or 'Child'.
+    // 'Module', 'Mix Task' or 'Child'.
     // Used to sort the results according to the 'sortingPriority'.
     // 'Child' means an item that belongs to a module (like Function, Callback or Type).
   }
@@ -63,10 +63,9 @@ function getSuggestions (term = '') {
   const nodes = sidebarNodes
 
   let modules = findIn(nodes.modules, term, 'Module')
-  let exceptions = findIn(nodes.exceptions, term, 'Exception')
   let tasks = findIn(nodes.tasks, term, 'Mix Task')
 
-  let results = [...modules, ...exceptions, ...tasks]
+  let results = [...modules, ...tasks]
 
   results = sort(results)
 
@@ -82,8 +81,8 @@ function getSuggestions (term = '') {
  */
 function sort (items) {
   return items.sort(function (item1, item2) {
-    const weight1 = sortingPriority[item1.category] || -1
-    const weight2 = sortingPriority[item2.category] || -1
+    const weight1 = getSortingPriority(item1)
+    const weight2 = getSortingPriority(item2)
 
     return weight2 - weight1
   }).sort(function (item1, item2) {
@@ -115,7 +114,8 @@ function findIn (elements, term, categoryName) {
         id: element.id,
         match: highlight(titleMatch),
         category: categoryName,
-        matchQuality: matchQuality(titleMatch)
+        matchQuality: matchQuality(titleMatch),
+        group: element.group
       }, element.id)
 
       results.push(parentResult)
@@ -199,7 +199,33 @@ function findMatchingChildren (elements, parentId, term, key) {
 }
 
 /**
- * How good th
+ * Chooses the right sorting priority for the given item.
+ *
+ * @param {Object} item Search result item.
+ *
+ * @returns {number} Sorting priority for a given item. Higher priority means higher position in search results.
+ */
+function getSortingPriority (item) {
+  if (isException(item)) {
+    return sortingPriority['Exception']
+  }
+
+  return sortingPriority[item.category] || -1
+}
+
+/**
+ * Is the given item an exception?
+ *
+ * @param {Object} item Search result item.
+ *
+ * @returns {boolean}
+ */
+function isException (item) {
+  return item.group === 'Exceptions'
+}
+
+/**
+ * How well search result marches the current query.
  *
  * @param {(Array|null)} match Information about the matched text (returned by String.match()).
  *

assets/js/events.js

@@ -16,7 +16,6 @@ import sidebarItemsTemplate from './templates/sidebar-items.handlebars'
 var SIDEBAR_TYPES = [
   '#extras-list',
   '#modules-list',
-  '#exceptions-list',
   '#tasks-list',
   '#search-list'
 ]

assets/test/autocomplete/suggestions.spec.js

@@ -3,11 +3,12 @@ import {getSuggestions} from '../../js/autocomplete/suggestions'
 describe('getSuggestions', () => {
   before(() => {
     window.sidebarNodes = {
-      exceptions: [{
-        id: 'My exception',
-        title: 'My exception'
-      }],
       modules: [
+        {
+          id: 'My exception',
+          title: 'My exception',
+          group: 'Exceptions'
+        },
         {
           id: 'Map',
           title: 'Map',
@@ -62,6 +63,7 @@ describe('getSuggestions', () => {
       expect(getSuggestions('Map').length).to.eql(1)
       expect(getSuggestions('Ecto.Repo').length).to.eql(1)
       expect(getSuggestions('phx.server').length).to.eql(1)
+      expect(getSuggestions('My exception').length).to.eql(1)
     })
 
     it('returns matching functions, callbacks and types', () => {
@@ -82,6 +84,7 @@ describe('getSuggestions', () => {
     })
 
     it('is case insensitive', () => {
+      expect(getSuggestions('My ExCePtIoN').length).to.eql(1)
       expect(getSuggestions('My ExCePtIoN')).to.eql(getSuggestions('my exception'))
     })
 
@@ -127,6 +130,12 @@ describe('getSuggestions', () => {
       expect(firstResult.label).to.eql('type')
     })
 
+    it('includes module name in function description', () => {
+      const firstResult = getSuggestions('get_by')[0]
+
+      expect(firstResult.description).to.eql('Ecto.Repo')
+    })
+
     it('generates a link for each suggestion', () => {
       expect(getSuggestions('has_many')[0].link).to.eql('Ecto.Schema.html#t:has_many/1')
       expect(getSuggestions('map')[0].link).to.eql('Map.html')

formatters/epub/dist/app-2497a22f0a216acd2721.js renamed to formatters/epub/dist/app-356e17b84785d966cf4f.js

@@ -26,8 +26,7 @@ defmodule ExDoc.Formatter.HTML do
     search_items = generate_search_items(project_nodes, extras, config)
 
     nodes_map = %{
-      modules: filter_list(:module, project_nodes),
-      exceptions: filter_list(:exception, project_nodes),
+      modules: filter_list(:module, project_nodes) |> group_exceptions(),
       tasks: filter_list(:task, project_nodes)
     }
 
@@ -47,7 +46,6 @@ defmodule ExDoc.Formatter.HTML do
         generate_search(nodes_map, config) ++
         generate_not_found(nodes_map, config) ++
         generate_list(nodes_map.modules, nodes_map, config) ++
-        generate_list(nodes_map.exceptions, nodes_map, config) ++
         generate_list(nodes_map.tasks, nodes_map, config) ++ generate_index(config)
 
     generate_build(all_files, build)
@@ -392,13 +390,25 @@ defmodule ExDoc.Formatter.HTML do
   end
 
   def filter_list(:module, nodes) do
-    Enum.filter(nodes, &(not (&1.type in [:exception, :task])))
+    Enum.filter(nodes, &(&1.type != :task))
   end
 
   def filter_list(type, nodes) do
     Enum.filter(nodes, &(&1.type == type))
   end
 
+  @exceptions_group_name "Exceptions"
+  defp group_exceptions(module_nodes) do
+    module_nodes
+    |> Enum.map(fn module_node ->
+      case module_node.type do
+        :exception -> %{module_node | group: @exceptions_group_name}
+        _ -> module_node
+      end
+    end)
+    |> Enum.sort_by(&(&1.type == :exception))
+  end
+
   defp generate_list(nodes, nodes_map, config) do
     nodes
     |> Task.async_stream(&generate_module_page(&1, nodes_map, config), timeout: :infinity)

formatters/html/dist/app-02948fd67e8f1d4dd1a5.js renamed to formatters/html/dist/app-a1d27018548e1b91d6b1.js

@@ -164,7 +164,7 @@ defmodule ExDoc.Formatter.HTML.Templates do
   defp logo_path(%{logo: nil}), do: nil
   defp logo_path(%{logo: logo}), do: "assets/logo#{Path.extname(logo)}"
 
-  defp sidebar_type(:exception), do: "exceptions"
+  defp sidebar_type(:exception), do: "modules"
   defp sidebar_type(:extra), do: "extras"
   defp sidebar_type(:module), do: "modules"
   defp sidebar_type(:behaviour), do: "modules"

lib/ex_doc/formatter/html.ex

@@ -14,17 +14,6 @@
   </section>
 <% end %>
 
-<%= if nodes_map.exceptions != [] do %>
-  <section class="details-list">
-    <h2 id="exceptions" class="section-heading">Exceptions</h2>
-    <div class="summary">
-      <%= for exception_node <- nodes_map.exceptions do
-        api_reference_entry_template(exception_node)
-      end %>
-    </div>
-  </section>
-<% end %>
-
 <%= if nodes_map.tasks != [] do %>
   <section class="details-list">
     <h2 id="tasks" class="section-heading">Mix Tasks</h2>

lib/ex_doc/formatter/html/templates.ex

@@ -46,10 +46,6 @@
       <li><a id="modules-list" href="#full-list">Modules</a></li>
     <% end %>
 
-    <%= if nodes_map.exceptions != [] do %>
-      <li><a id="exceptions-list" href="#full-list">Exceptions</a></li>
-    <% end %>
-
     <%= if nodes_map.tasks != [] do %>
       <li><a id="tasks-list" href="#full-list">Mix Tasks</a></li>
     <% end %>

lib/ex_doc/formatter/html/templates/api_reference_template.eex

@@ -215,6 +215,15 @@ defmodule ExDoc.Formatter.HTMLTest do
              ~r{"id":"Common\.Nesting\.Prefix\.Bar","nested_context":"Common\.Nesting\.Prefix","nested_title":"Bar","title":"Common\.Nesting\.Prefix\.Bar"}ms
   end
 
+  test "groups exceptions" do
+    generate_docs(doc_config())
+
+    content = read_wildcard!("#{output_dir()}/dist/sidebar_items-*.js")
+
+    assert content =~
+             ~r{"group":"Exceptions","id":"RandomError","title":"RandomError"}ms
+  end
+
   describe "generates logo" do
     test "overriding previous entries" do
       File.mkdir_p!("#{output_dir()}/assets")
@@ -302,7 +311,6 @@ defmodule ExDoc.Formatter.HTMLTest do
 
       content = read_wildcard!("#{output_dir()}/dist/sidebar_items-*.js")
       assert content =~ ~s("modules":[])
-      assert content =~ ~s("exceptions":[])
 
       assert content =~
                ~s("extras":[{"group":"","headers":[],"id":"api-reference","title":"API Reference"},)