I wrote the ReadMeUtils class a long time ago as a way to make documenting the REST endpoints easier. The Controller class methods are annotated so that endpoint documentation is displayed in Swagger but it is also duplicated in the README. It seemed like a good idea at the time to provide a utility to make this easier so that you only had to document in one place. It was actually helpful (to me anyways) when we first introduced a large number of REST endpoints and saved some tedious copy/pasting.
In hindsight, there was no way of enforcing that we use the utility along with the `README.vm` template. People intuitively edit the README.md instead and the template quickly became stale. Eventually I got tired of keeping the template in sync so I stopped using it as well. This class can (and should) be safely removed. On Wed, Nov 29, 2017 at 7:16 AM, justinleet <g...@git.apache.org> wrote: > Github user justinleet commented on the issue: > > https://github.com/apache/metron/pull/852 > > Glancing briefly, it looks like `ReadMeUtils` uses it as a template > for the metron-rest README.md. Just running the main in there overwrites > the metron-rest README.md. Which seems very odd, given that `ReadMeUtils` > is in the test package. > > There seems to be no documentation of this class, or its purpose, and > I didn't dig enough into the code to figure it out. Even not knowing the > details and assuming I'm not misreading what's happening, I don't like that > there's an expectation of editing a `README.vm` file, then running a > program to produce the final output `README.md`. `README.md` can vary > independently of `README.vm`. And it already has. > > It's outside the scope of this ticket, but at minimum, that class > needs to be moved out of test, it needs to be actually documented what the > purpose of it is, the steps to use it, etc. Right now, though, unless > someone comes up with a compelling reason not to, I'm in favor of killing > it entirely. I don't ever see that being properly managed, even if it does > have some utility built in. > > > --- >
