Hi there Rob, thank you so much for your interest, very appreciated! Please read my inline replies, in order to have a better readability. Have a great day, all the best! ~Simo
http://people.apache.org/~simonetripodi/ On Tue, Jul 31, 2018 at 5:10 PM Robert Munteanu <[email protected]> wrote: > Hi Simo, > > On Tue, 2018-07-31 at 14:06 +0200, Simone Tripodi wrote: > > Hi all, > > due to a private need I implemented a tool that, as a Sling > > committer, I > > would like to promote inside this community in order to have it as a > > public > > domain. > > > > The basic idea is to automate the production of documentation, > > providing to > > both developers and customers a centralised documentation of all HTTP > > entry > > points and Metatype configurations. > > This looks nice, thanks for bringing it up for discussion. I think we > could use a tool to enhance documentation for Sling. > > A couple of notes/questions: > > 1. The sample markdown output is wrapped, it would be more useful if > attached as a plain-text file. > please have a look at the following public gists! * created output files: https://gist.github.com/simonetripodi/7f4d0ecaf697c222afc1ec89dac55f47 * a Metatype sample file: https://gist.github.com/simonetripodi/7664657ff3b00577b0c7bc78f6b20492 * servlet sample file: https://gist.github.com/simonetripodi/1b8f57f27b6b5f7c2792b3540d8c0230 > > 2. Is there any support for removing certain classes or properties from > the output? I can see situations where we don't want to expose > something, based on whether it's deprecated or internal. > > Properties marked as "private" are skipped already and not shown in the final report, I did not added a way to skip classes - guess I am still in time in order to add such support! :P > 3. Is there support (or planned support) for adding additional data to > the output? I think a plain descriptive output for a certain component > is good, but it might be useful to complement it with other > information, such as a free-text description. > I think it wouldn't be hard adding such feature - please take also in consideration that description field is present to almost all supported annotations, but adding an additional input where getting extra text is something we can integrate > > 4. Does this tool depend on Sling in any matter? Briefly looking over > your email it looks like it builds on top of the OSGi annotations ( + > Felix/Sling specific ones ) so it could also potentially find a home in > the Felix project. > > There is no direct dependency to Sling in any way, excluding the @SlingServlet annotation, the tool imports just a couple of utility dependencies. I have no karma in Felix but, given a wider general purpose of this tool -it can potentially include other stuff- I would suggest to Sling having a home to host the "docgen", while Felix is more OSGi-focused, WDYT? I have a couple of questions from my side: * do I need to publish the sourcecode to a public personal or Apache repo? * does my company needs to sign the CLA for this component? TIA! ~Simo > Thanks! > > Robert > >
