Dan, First, very happy to see you're planning to contribute.
So this is a great idea! A few things to consider here: - At what point in the application lifecycle to create automatic processor/extension documentation 1) Build phase: Best done via a Maven plugin probably. 2) Startup Phase: Could be part of the nar loading/extension service provider hunt. 3) On demand: As a request comes to view-usage or look at the extension listing generate the processor/extension docs. Given that it would likely be purely static content any of these approaches are reasonable. My estimation then is that the ease of implementation in order is 3, 2, 1. So you might consider approaching this that way. Do option 3 since that code would be reusable. If we find that isn't good enough then go option 2. If we think we need earliest possible binding then option 3. We can just grow through it if needed. But KISS probably points at 3 in my opinion. Also as Benson pointed out in another thread we're likely heading down the path of having a separate Git repo for Maven specific plugins/archetypes. So you might want to hold off on the maven part specifically until that stabilizes too. Consideration for the generation beyond (when): - What if the developer already supplies processor docs? Perhaps auto-generation only kicks in if they've not done this. Or maybe we provide both (auto generated and developer generated)...something to thing about. Very cool that you're wanting to take a stab at this. I think it will be really helpful and it ensures maximum bang for the buck on those annotations for users. Thanks! Joe On Sun, Jan 11, 2015 at 1:23 PM, Mark Payne <[email protected]> wrote: > Dan, > > Matt and I discussed this approach before but ultimately decided that we > like the idea of just auto generating the docs on demand with a "More Info" > type of link that lets you add more in html format if you care to do so. > > Others' thoughts and ideas are welcome though! > > Sent from my iPhone > > > On Jan 11, 2015, at 12:32 PM, Daniel Bress <[email protected]> > wrote: > > > > Hi All, > > > > Just pulled down the code out of Git and got everything up and running > on Windows. This was pretty simple, and the UI looks great under chrome. > > > > > > I was thinking of writing a maven plugin to generate the processor > usage HTML documentation. > > > > > > Looking through the existing processor documentation, it seems like > most of this information comes directly from the code in the processors, > via @CapabilityDescription, and the PropertyDescriptors and Relationships. > Then if your processor only requires this level of documentation in the > HTML format, you could tie this plugin to the build, and keep your inline > processor documentation in sync with the HTML documentation. > > > > > > What do you think? > > > > > > Dan Bress > > Software Engineer > > ONYX Consulting Services >
