pseudomuto / protoc-gen-doc

Documentation generator plugin for Google Protocol Buffers
MIT License
2.61k stars 462 forks source link

Additional separator for exclude filters #427

Open sf-jassmith opened 4 years ago

sf-jassmith commented 4 years ago

When using the gradle plugin for protoc it does not allow for passing additional command args for example there is not way to set --doc_opt . Instead it relies on the fact that protoc splits the --doc_out parameter on : and passes anything before the colon to the compile plugin method as an arg and everything after the colon as the output directory for the plugin. This is great because in theory it should be possible to configure this plugin like so --doc_out <TYPE|TEMPLATE_FILE>,<OUTPUT_FILE>:<EXCLUDE_PATTERN>,<EXCLUDE_PATTERN>*:

Example

--doc_out markdown,protobuf_doc.md:Ignore*:the/output/directory

The unfortunate problem is that the : separator that protoc chose for indicating the end of options is the same as the exclude pattern separator that was chosen by this plugin and so the result is that the args passed to compile don't contain the exclude patterns but instead they are prepended to the output directory causing a "Directory does not exist" error.

Proposed solution to this problem is to accept an additional separator so that --doc_opt remains backwards compatible and it is also possible to use the --doc_out kludge to configure the exclude patterns from the gradle plugin.

Example:

--doc_out markdown,protobuf_doc.md~Ignore*:the/output/directory

∼ is sometimes used as a negation or "not" symbol in set theory