markvincze
commented
7 months ago Hi @fclad,
Thank for submitting the issue, I'm glad you like the library!
The rationale was just to have a deterministic ordering, so that if we have a lot of types, then make it easy to find a specific type in the list by eye. And this seemed to be the approach used by other documentation generators out there, for example methods in a C# class:
Or methods in a Java interface:
But I understand that sometimes it would be useful to preserve the ordering which was in the original proto files, as it can be more logical than the alphabetical.
One thing I don't know is whether protoc preserves the original order, when it creates the binary descriptor, and especially what it does if there were multiple proto files specified in the input.
I'll check if that works correctly, and add a parameter to the toml config with which this can be controlled, so you can choose between alphabetical ordering, or preserving the original order.
Awesome tool that you've developed! I've been looking a long time for a good gRPC documentation generator and sabledocs is by far the best I've seen.
One comment is that it may be better to see the messages in the documentation in the same order as they are in the .proto file.
Currently, they seem to be ordered alphabetically and I'm curious what is the rationale behind this choice.
https://github.com/markvincze/sabledocs/blob/2421ae8926322ca911600dfe4f0d81963b7ae300/src/sabledocs/proto_descriptor_parser.py#L182