bitwalker / bitwalker/exprotobuf

Automatically generate protobuf message documentation

Open
#108 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Elixir
Stars
482
Forks
68
PR merge metrics
No merged PRs in 30d

Description

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](https://user-images.githubusercontent.com/6473994/64478428-5e4d9680-d176-11e9-999f-3567ca17ee7a.png)

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](https://user-images.githubusercontent.com/6473994/64478565-04e66700-d178-11e9-93f1-ed0b835a1b40.png)

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](https://user-images.githubusercontent.com/6473994/64478626-aa013f80-d178-11e9-9249-08511f38b27b.png)

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).

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.