bitwalker / exprotobuf

Protocol Buffers in Elixir made easy!
Apache License 2.0
486 stars 69 forks source link

Automatically generate protobuf message documentation #108

Open Doom4535 opened 5 years ago

Doom4535 commented 5 years ago

Is there a way to link this into ex_doc such that the message structure is included in the generated documentation?

For example

defmodule Messages do
  @moduledoc """
  Some documentation
  """
  use Protobuf, """
    message Msg {
      message SubMsg {
        required uint32 value = 1;
      }

      enum Version {
        V1 = 1;
        V2 = 2;
      }

      required Version version = 2;
      optional SubMsg sub = 1;
    }
  """
end

Gives me this: exprotobuf_test_no_doc

It would be nice if there was a way to trigger behavior that was more like this:

defmodule Messages do
  @moduledoc """
  Some documentation
  """

  @doc """
  message Msg {
    message SubMsg {
      required uint32 value = 1;
    }
  }
  """
  def _submsg do
  end

  @doc """
  enum Version {
    V1 = 1;
    V2 = 2;
  }
  """
  def _version do
  end

  @doc """
  required Version version = 2;
  """
  def version do
  end

  @doc """
  optional SubMsg sub = 1;
  """
  def sub do
  end

  use Protobuf, """
    message Msg {
      message SubMsg {
        required uint32 value = 1;
      }

      enum Version {
        V1 = 1;
        V2 = 2;
      }

      required Version version = 2;
      optional SubMsg sub = 1;
    }
  """
end

Giving an output like this: exprotobuf_test_expanded_doc

Or like this:

defmodule Messages do
  @moduledoc """
  Some documentation
  """
  @doc """
  message Msg {
    message SubMsg {
      required uint32 value = 1;
    }

    enum Version {
      V1 = 1;
      V2 = 2;
    }

    {
      required Version version = 2;
      optional SubMsg sub = 1;
    }
  }
  """
  use Protobuf, """
    message Msg {
      message SubMsg {
        required uint32 value = 1;
      }

      enum Version {
        V1 = 1;
        V2 = 2;
      }

      required Version version = 2;
      optional SubMsg sub = 1;
    }
  """
end

Giving an output like this: exprotobuf_test_src_doc

The last one is where the protobuf source (and any comments) are copied in to serve as their own documentation.

Something like this would be most useful when used to import *.proto files, allowing the built documents to always reflect the version of the .proto files that are in use.

The closest issue that I found to this was https://github.com/bitwalker/exprotobuf/pull/48; however, I have been unable to get my project to show the imported protobufs (making me think that there is some other code difference between these two).