Improve Examples and LiveExample docs

rename test files and modules related to LiveExample

lib/surface/catalogue/examples.ex

@@ -37,9 +37,9 @@ defmodule Surface.Catalogue.Examples do
       has no effect when direction is "vertical".
 
     * `assert` - Optional. When using `catalogue_test/1`, generates simple `=~` assertions for
-      the given text or list of texts. This option is available only for Examples, not Playgrounds.
+      the given text or list of texts.
 
-  When defined at the module level, i.e. passing to `use Surface.Catalogue.Example, ...`, the
+  When defined at the module level, i.e. passing to `use Surface.Catalogue.Examples, ...`, the
   options apply to all examples. Aside from `subject` and `catalogue`, options can be overridden
   at the function level using the `@example` module attribute.
 

lib/surface/catalogue/live_example.ex

@@ -1,5 +1,6 @@
 defmodule Surface.Catalogue.LiveExample do
-  @moduledoc """
+  @moduledoc since: "0.12.0"
+  @moduledoc ~S'''
   A generic LiveView to create a single live example for the Surface Catalogue.
 
   Use `LiveExample` if your example requires manipulating state (data) through
@@ -8,22 +9,22 @@ defmodule Surface.Catalogue.LiveExample do
 
   ## Options
 
-  Besides the buit-in options provided by the LiveView itself, an Example also
+  Besides the buit-in options provided by the LiveView itself, a LiveExample also
   provides the following options:
 
     * `subject` - Required. The target component of the Example.
 
-    * `height` - Required. The height of the Example.
-
     * `catalogue` - Optional. A module that implements the `Surface.Catalogue`
       providing additional information to the catalogue tool. Usually required
       if you want to share your components as a library.
 
-    * `body` - Optional. Sets/overrides the attributes of the the Example's body tag.
-      Useful to set a different background or padding.
+    * `height` - Required. The height of the Example.
 
     * `title` - Optional. The title of the example.
 
+    * `body` - Optional. Sets/overrides the attributes of the the Example's body tag.
+      Useful to set a different background or padding.
+
     * `direction` - Optional. Defines how the example + code boxes should be displayed.
       Available values are "horizontal" or "vertical". Default is "horizontal" (side-by-side).
 
@@ -34,7 +35,23 @@ defmodule Surface.Catalogue.LiveExample do
     * `assert` - Optional. When using `catalogue_test/1`, generates simple `=~` assertions for
       the given text or list of texts.
 
-  """
+  ## Example
+
+      defmodule MyApp.Catalogue.MyComponentExample do
+        use Surface.Catalogue.LiveExample,
+          subject: MyApp.MyComponent,
+          title: "An example for MyComponent",
+          assert: ["Value is 0"]
+
+        data value, :integer, default: 0
+
+        def render(assigns) do
+          ~F"""
+          <MyApp.MyComponent {=value}/>
+          """
+        end
+      end
+  '''
 
   defmacro __using__(opts) do
     subject = Surface.Catalogue.fetch_subject!(opts, __MODULE__, __CALLER__)

test/support/catalogue/fake_example.ex → test/support/catalogue/fake_live_example.ex

@@ -1,4 +1,4 @@
-defmodule Surface.Catalogue.FakeExample do
+defmodule Surface.Catalogue.FakeLiveExample do
   use Surface.Catalogue.LiveExample,
     subject: Surface.FakeComponent,
     title: "A fake example",

test/support/catalogue/fake_example_moduledoc.ex → test/support/catalogue/fake_live_example_moduledoc.ex

@@ -1,4 +1,4 @@
-defmodule Surface.Catalogue.FakeExampleModuleDocFalse do
+defmodule Surface.Catalogue.FakeLiveExampleModuleDocFalse do
   @moduledoc false
 
   use Surface.Catalogue.LiveExample,

test/support/catalogue/fake_example_with_user_config.ex → test/support/catalogue/fake_live_example_with_user_config.ex

@@ -1,4 +1,4 @@
-defmodule Surface.Catalogue.FakeExampleWithUserConfig do
+defmodule Surface.Catalogue.FakeLiveExampleWithUserConfig do
   use Surface.Catalogue.LiveExample,
     subject: Surface.FakeComponent,
     head_css: "User's fake css",

test/support/live_view_test/fake_example.ex → test/support/live_view_test/fake_live_example.ex

@@ -1,4 +1,4 @@
-defmodule Surface.LiveViewTestTest.FakeExample do
+defmodule Surface.LiveViewTestTest.FakeLiveExample do
   use Surface.Catalogue.LiveExample,
     subject: Surface.LiveViewTestTest.FakeComponent,
     title: "A fake example",

test/support/live_view_test/fake_example_for_other_fake_component.ex → test/support/live_view_test/fake_live_example_for_other_fake_component.ex

@@ -1,4 +1,4 @@
-defmodule Surface.LiveViewTestTest.FakeExampleForOtherFakeComponent do
+defmodule Surface.LiveViewTestTest.FakeLiveExampleForOtherFakeComponent do
   use Surface.Catalogue.LiveExample,
     subject: Surface.LiveViewTestTest.OtherFakeComponent,
     title: "A fake example"

test/surface/catalogue/catalogue_test.exs

@@ -1,9 +1,9 @@
 defmodule Surface.Catalogue.CatalogueTest do
   use ExUnit.Case
 
-  alias Surface.Catalogue.FakeExample
+  alias Surface.Catalogue.FakeLiveExample
   alias Surface.Catalogue.FakePlayground
-  alias Surface.Catalogue.FakeExampleWithUserConfig
+  alias Surface.Catalogue.FakeLiveExampleWithUserConfig
 
   setup do
     Application.delete_env(:surface_catalogue, :assets_config)
@@ -12,7 +12,7 @@ defmodule Surface.Catalogue.CatalogueTest do
 
   describe "get_config/1" do
     test "get default configuration if none is provided" do
-      config = Surface.Catalogue.get_config(FakeExample)
+      config = Surface.Catalogue.get_config(FakeLiveExample)
 
       assert config[:head_css] =~ "/assets/app.css"
       assert config[:head_js] =~ "/assets/app.js"
@@ -24,7 +24,7 @@ defmodule Surface.Catalogue.CatalogueTest do
         head_js: "Configs's fake head js"
       )
 
-      config = Surface.Catalogue.get_config(FakeExample)
+      config = Surface.Catalogue.get_config(FakeLiveExample)
 
       assert config[:head_css] =~ "Configs's fake head css"
       assert config[:head_js] =~ "Configs's fake head js"
@@ -38,7 +38,7 @@ defmodule Surface.Catalogue.CatalogueTest do
     end
 
     test "user config overrides default and catalogue configs" do
-      config = Surface.Catalogue.get_config(FakeExampleWithUserConfig)
+      config = Surface.Catalogue.get_config(FakeLiveExampleWithUserConfig)
 
       assert config[:head_css] =~ "User's fake css"
       assert config[:head_js] =~ "User's fake js"

test/surface/catalogue/live_example_test.exs

@@ -1,29 +1,29 @@
 defmodule Surface.Catalogue.LiveExampleTest do
   use ExUnit.Case
 
-  alias Surface.Catalogue.FakeExample
-  alias Surface.Catalogue.FakeExampleModuleDocFalse
+  alias Surface.Catalogue.FakeLiveExample
+  alias Surface.Catalogue.FakeLiveExampleModuleDocFalse
 
   test "saves subject as metadata" do
-    meta = Surface.Catalogue.get_metadata(FakeExample)
+    meta = Surface.Catalogue.get_metadata(FakeLiveExample)
 
     assert meta.subject == Surface.FakeComponent
   end
 
   test "saves render/1's content as metadata" do
-    [meta] = Surface.Catalogue.get_metadata(FakeExample).examples_configs
+    [meta] = Surface.Catalogue.get_metadata(FakeLiveExample).examples_configs
 
     assert Keyword.fetch!(meta, :code) == "The code\n"
   end
 
   test "saves user config" do
-    config = Surface.Catalogue.get_config(FakeExample)
+    config = Surface.Catalogue.get_config(FakeLiveExample)
 
     assert config[:title] == "A fake example"
   end
 
   test "saves render/1's content as metadata when moduledoc is false" do
-    [meta] = Surface.Catalogue.get_metadata(FakeExampleModuleDocFalse).examples_configs
+    [meta] = Surface.Catalogue.get_metadata(FakeLiveExampleModuleDocFalse).examples_configs
 
     assert Keyword.fetch!(meta, :code) == "The code\n"
   end

test/surface/live_view_test_test.exs

@@ -41,13 +41,13 @@ defmodule Surface.LiveViewTestTest do
       tests = get_test_functions(Surface.LiveViewTestTest.PassingCatalogueSubjectTests)
 
       assert tests == [
-               # Using Example
-               {:"test Surface.LiveViewTestTest.FakeExample.render", 1},
                # Using Examples
                {:"test Surface.LiveViewTestTest.FakeExamples.example_with_assert_text", 1},
                {:"test Surface.LiveViewTestTest.FakeExamples.example_with_assert_texts", 1},
                {:"test Surface.LiveViewTestTest.FakeExamples.example_with_opts", 1},
                {:"test Surface.LiveViewTestTest.FakeExamples.example_without_opts", 1},
+               # Using LiveExample
+               {:"test Surface.LiveViewTestTest.FakeLiveExample.render", 1},
                # Using Playground
                {:"test Surface.LiveViewTestTest.FakePlayground", 1}
              ]
@@ -56,15 +56,15 @@ defmodule Surface.LiveViewTestTest do
     test "passing :all" do
       tests = get_test_functions(Surface.LiveViewTestTest.PassingCatalogueAllTests)
 
-      assert {:"test Surface.LiveViewTestTest.FakeExample.render", 1} in tests
-      assert {:"test Surface.LiveViewTestTest.FakeExampleForOtherFakeComponent.render", 1} in tests
+      assert {:"test Surface.LiveViewTestTest.FakeLiveExample.render", 1} in tests
+      assert {:"test Surface.LiveViewTestTest.FakeLiveExampleForOtherFakeComponent.render", 1} in tests
     end
 
     test "passing :all with the :except option" do
       tests = get_test_functions(Surface.LiveViewTestTest.PassingCatalogueAllAndExceptTests)
 
-      assert {:"test Surface.LiveViewTestTest.FakeExample.render", 1} in tests
-      refute {:"test Surface.LiveViewTestTest.FakeExampleForOtherFakeComponent.render", 1} in tests
+      assert {:"test Surface.LiveViewTestTest.FakeLiveExample.render", 1} in tests
+      refute {:"test Surface.LiveViewTestTest.FakeLiveExampleForOtherFakeComponent.render", 1} in tests
     end
 
     test "warns when passing an undefined module (subject)" do