basics on getting documentation through

lib/zig.doc/generator.ex

@@ -33,32 +33,24 @@ defmodule Zig.Doc.Generator do
   defp trim_first_space(<<32, next, rest::binary>>) when next != 32, do: <<next, rest::binary>>
   defp trim_first_space(line), do: line
 
-  defp context do
-    case :code.priv_dir(:zigler) do
-      {:error, :bad_name} -> ""
-      path -> Path.join(path, "beam/sema_doc.zig")
-    end
-  end
-
   def modulenode_from_config({id, options}, exdoc_config, sema_module) do
     # options must include 'file' key
     with {:ok, file_path} <- Keyword.fetch(options, :file),
-         {{:ok, file}, :read, _} <- {File.read(file_path), :read, file_path},
-         {{:ok, sema}, :sema, _} <-
-           {sema_module.run_sema(file_path, nil, sema_context: context()), :sema, file_path} do
+         {{:ok, file}, :read, _} <- {File.read(file_path), :read, file_path} do
+      sema = sema_module.run_sema_doc(file_path)
       parsed_document = Zig.Parser.parse(file)
 
       node = %ExDoc.ModuleNode{
         id: "#{id}",
-        doc_line: 1,
+        # doc_line: 1,
         doc: doc_ast(parsed_document, file_path),
         language: ExDoc.Language.Elixir,
         title: "beam",
         group: :"zig code",
         module: :beam,
         docs_groups: [:Functions, :Types, :Constants, :Variables],
         type: :module,
-        source_path: file_path,
+        # source_path: file_path,
         source_url: source_url(file_path, 1, exdoc_config)
       }
 
@@ -71,11 +63,8 @@ defmodule Zig.Doc.Generator do
           "zig doc config error: configuration for module #{id} requires a `:file` option"
         )
 
-      {{:error, reason}, :read, path} ->
+      {{:error, reason}, path} ->
         Mix.raise("zig doc error: failure reading file at `#{path}` (#{reason})")
-
-      {{:error, _reason}, :sema, path} ->
-        Mix.raise("zig doc error: sema failed for `#{path}`")
     end
   end
 
@@ -211,7 +200,7 @@ defmodule Zig.Doc.Generator do
           signature: "#{name}",
           doc: doc_ast(const, file_path, extras: extras),
           spec: Spec.type_from_sema(this_type),
-          source_path: file_path,
+          # source_path: file_path,
           source_url: source_url(file_path, elem(const.location, 0), exdoc_config)
         }
 
@@ -230,7 +219,7 @@ defmodule Zig.Doc.Generator do
           signature: signature,
           specs: [spec],
           group: :Constants,
-          source_path: file_path,
+          # source_path: file_path,
           source_url: source_url(file_path, elem(const.location, 0), exdoc_config)
         }
 
@@ -270,7 +259,7 @@ defmodule Zig.Doc.Generator do
           specs: specs,
           group: :Variables,
           annotations: annotations,
-          source_path: file_path,
+          # source_path: file_path,
           source_url: source_url(file_path, elem(var.location, 0), exdoc_config)
         }
 
@@ -303,7 +292,7 @@ defmodule Zig.Doc.Generator do
       signature: signature,
       specs: specs,
       group: group,
-      source_path: file_path,
+      # source_path: file_path,
       source_url: source_url(file_path, elem(parameters.location, 0), exdoc_config)
     }
 
@@ -319,7 +308,7 @@ defmodule Zig.Doc.Generator do
       doc: doc_ast(parameters, file_path),
       arity: arity,
       spec: Spec.typefun_from_sema(sema),
-      source_path: file_path,
+      # source_path: file_path,
       source_url: source_url(file_path, elem(parameters.location, 0), exdoc_config)
     }
 
@@ -330,6 +319,10 @@ defmodule Zig.Doc.Generator do
   file = Path.join(__DIR__, "markdown_from_typedef.md.eex")
   EEx.function_from_file(:defp, :markdown_from_typedef, file, [:assigns])
 
+  defp tts(atom) when is_atom(atom), do: atom
+
+  defp tts({:ref, list}), do: Enum.join(list, ".")
+
   defp render_type(type) when is_atom(type), do: to_string(type)
 
   defp render_type({:slice, opts, params}) do
@@ -365,9 +358,21 @@ defmodule Zig.Doc.Generator do
 
       %Zig.Parser.Pointer{count: :slice} ->
         "[]#{render_type(type.type)}"
+
+      %{optional: true} when struct == Zig.Type.Pointer ->
+        "?*#{render_type(type.child)}"
+
+      %{optional: false} when struct == Zig.Type.Pointer ->
+        "*#{render_type(type.child)}"
     end
   end
 
+  defp render_type({:call, :TypeOf, params}), do: render_type({:call, "@TypeOf", params})
+
+  defp render_type({:call, fun, params}) do
+    "#{fun}(#{Enum.map_join(params, ", ", &render_type/1)})"
+  end
+
   defp render_struct(%{name: "stub_erl_nif." <> what}), do: "e.#{what}"
   defp render_struct(%{name: "beam.term" <> _}), do: "beam.term"
   defp render_struct(%{name: name}), do: name

lib/zig.doc/markdown_from_typedef.md.eex

@@ -1,15 +1,15 @@
 <%= unless @fields == [] do %>
 ### fields
 <%= for field <- @fields do %>
-- `<%= field.name %>`: `<%= field.type %>`
+- `<%= field.name %>`: `<%= tts(field.type) %>`
   <%= if comment = Map.get(field, :comment), do: comment %>
 <% end %>
 <% end %>
 
 <%= unless @consts == [] do %>
 ### consts
 <%= for const <- @consts do %>
-- `<%= const.name %>`: `<%= const.type %>`
+- `<%= const.name %>`: `<%= tts(const.type) %>`
   <%= if comment = Map.get(const, :comment), do: comment %>
 <% end %>
 <% end %>
@@ -21,7 +21,7 @@
 <% 
   arg_types = function.params 
   |> Enum.map(fn 
-    %{name: name, type: type} -> "#{name}: #{type}"
+    %{name: name, type: type} -> "#{name}: #{tts(type)}"
     type -> to_string(type)
   end) 
   |> Enum.join(", ") 

lib/zig.doc/spec.ex

@@ -42,6 +42,15 @@ defmodule Zig.Doc.Spec do
 
       Zig.Type.Enum ->
         String.to_atom(type.name)
+
+      Zig.Type.Pointer when type.optional ->
+        :"?*#{render_type(type.child)}"
+
+      Zig.Type.Pointer ->
+        :"*#{render_type(type.child)}"
+
+      Zig.Type.Bool ->
+        :bool
     end
   end
 
@@ -72,6 +81,9 @@ defmodule Zig.Doc.Spec do
         |> Enum.map(fn {tag, _} -> wrap(:".#{tag}") end)
         |> Enum.reduce(&{:|, [], [&1, &2]})
 
+      {Zig.Type.Pointer, %{child: child}} ->
+        wrap(:"*#{render_type(child)}")
+
       _ ->
         :unknown
     end

mix.exs

@@ -4,7 +4,7 @@ defmodule ZigDoc.MixProject do
   def project do
     [
       app: :zig_doc,
-      version: "0.3.1",
+      version: "0.4.0",
       elixir: "~> 1.14",
       start_permanent: Mix.env() == :prod,
       elixirc_paths: elixirc_paths(Mix.env()),
@@ -36,10 +36,10 @@ defmodule ZigDoc.MixProject do
     [
       # zig_doc is tied to specific versions of ex_doc.
       # it uses some forbidden "private" functions.
-      {:ex_doc, "~> 0.30.9"},
+      {:ex_doc, "~> 0.34.2"},
       # this is also pinned to a version of zig_parser because
       # versions of zig_parser are pinned to zig versions.
-      {:zig_parser, "~> 0.3.0"},
+      {:zig_parser, "~> 0.4.0"},
       {:mox, "~> 1.0", only: :test}
     ]
   end

mix.lock

@@ -1,11 +1,11 @@
 %{
-  "earmark_parser": {:hex, :earmark_parser, "1.4.37", "2ad73550e27c8946648b06905a57e4d454e4d7229c2dafa72a0348c99d8be5f7", [:mix], [], "hexpm", "6b19783f2802f039806f375610faa22da130b8edc21209d0bff47918bb48360e"},
-  "ex_doc": {:hex, :ex_doc, "0.30.9", "d691453495c47434c0f2052b08dd91cc32bc4e1a218f86884563448ee2502dd2", [:mix], [{:earmark_parser, "~> 1.4.31", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1", [hex: :makeup_erlang, repo: "hexpm", optional: false]}], "hexpm", "d7aaaf21e95dc5cddabf89063327e96867d00013963eadf2c6ad135506a8bc10"},
-  "makeup": {:hex, :makeup, "1.1.0", "6b67c8bc2882a6b6a445859952a602afc1a41c2e08379ca057c0f525366fc3ca", [:mix], [{:nimble_parsec, "~> 1.2.2 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "0a45ed501f4a8897f580eabf99a2e5234ea3e75a4373c8a52824f6e873be57a6"},
-  "makeup_elixir": {:hex, :makeup_elixir, "0.16.1", "cc9e3ca312f1cfeccc572b37a09980287e243648108384b97ff2b76e505c3555", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "e127a341ad1b209bd80f7bd1620a15693a9908ed780c3b763bccf7d200c767c6"},
-  "makeup_erlang": {:hex, :makeup_erlang, "0.1.2", "ad87296a092a46e03b7e9b0be7631ddcf64c790fa68a9ef5323b6cbb36affc72", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "f3f5a1ca93ce6e092d92b6d9c049bcda58a3b617a8d888f8e7231c85630e8108"},
+  "earmark_parser": {:hex, :earmark_parser, "1.4.41", "ab34711c9dc6212dda44fcd20ecb87ac3f3fce6f0ca2f28d4a00e4154f8cd599", [:mix], [], "hexpm", "a81a04c7e34b6617c2792e291b5a2e57ab316365c2644ddc553bb9ed863ebefa"},
+  "ex_doc": {:hex, :ex_doc, "0.34.2", "13eedf3844ccdce25cfd837b99bea9ad92c4e511233199440488d217c92571e8", [:mix], [{:earmark_parser, "~> 1.4.39", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_c, ">= 0.1.0", [hex: :makeup_c, repo: "hexpm", optional: true]}, {:makeup_elixir, "~> 0.14 or ~> 1.0", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1 or ~> 1.0", [hex: :makeup_erlang, repo: "hexpm", optional: false]}, {:makeup_html, ">= 0.1.0", [hex: :makeup_html, repo: "hexpm", optional: true]}], "hexpm", "5ce5f16b41208a50106afed3de6a2ed34f4acfd65715b82a0b84b49d995f95c1"},
+  "makeup": {:hex, :makeup, "1.1.2", "9ba8837913bdf757787e71c1581c21f9d2455f4dd04cfca785c70bbfff1a76a3", [:mix], [{:nimble_parsec, "~> 1.2.2 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "cce1566b81fbcbd21eca8ffe808f33b221f9eee2cbc7a1706fc3da9ff18e6cac"},
+  "makeup_elixir": {:hex, :makeup_elixir, "0.16.2", "627e84b8e8bf22e60a2579dad15067c755531fea049ae26ef1020cad58fe9578", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "41193978704763f6bbe6cc2758b84909e62984c7752b3784bd3c218bb341706b"},
+  "makeup_erlang": {:hex, :makeup_erlang, "1.0.1", "c7f58c120b2b5aa5fd80d540a89fdf866ed42f1f3994e4fe189abebeab610839", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "8a89a1eeccc2d798d6ea15496a6e4870b75e014d1af514b1b71fa33134f57814"},
   "mox": {:hex, :mox, "1.1.0", "0f5e399649ce9ab7602f72e718305c0f9cdc351190f72844599545e4996af73c", [:mix], [], "hexpm", "d44474c50be02d5b72131070281a5d3895c0e7a95c780e90bc0cfe712f633a13"},
-  "nimble_parsec": {:hex, :nimble_parsec, "1.3.1", "2c54013ecf170e249e9291ed0a62e5832f70a476c61da16f6aac6dca0189f2af", [:mix], [], "hexpm", "2682e3c0b2eb58d90c6375fc0cc30bc7be06f365bf72608804fb9cffa5e1b167"},
+  "nimble_parsec": {:hex, :nimble_parsec, "1.4.0", "51f9b613ea62cfa97b25ccc2c1b4216e81df970acd8e16e8d1bdc58fef21370d", [:mix], [], "hexpm", "9c565862810fb383e9838c1dd2d7d2c437b3d13b267414ba6af33e50d2d1cf28"},
   "pegasus": {:hex, :pegasus, "0.2.4", "3d8d5a2c89552face9c7ca14f959cc6c6d2cd645db1df85940db4c77c3b21a24", [:mix], [{:nimble_parsec, "~> 1.2", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "2d21e2b6b946fe3cd441544bf9856e7772f29050332f0255e166a13cdbe65bb4"},
-  "zig_parser": {:hex, :zig_parser, "0.3.0", "2a597ae6990447e70e46691d9ca7073afb3c3e13ab143dce1df0865a764c48f4", [:mix], [{:pegasus, "~> 0.2.4", [hex: :pegasus, repo: "hexpm", optional: false]}], "hexpm", "6b90ee53cf23e53824dbdad2d2ca597a1cb8d882b0748638921bddda1563a736"},
+  "zig_parser": {:hex, :zig_parser, "0.4.0", "5230576fcea30c061f08f6053448ad3dc5194a45485065564a7f8047bb351ce9", [:mix], [{:pegasus, "~> 0.2.4", [hex: :pegasus, repo: "hexpm", optional: false]}], "hexpm", "ec54cf14e80a1485e29a80b42756d0421426db81eb9e2630721fd46ab5c21bcb"},
 }