Hi Simo, See further inline
On Tue, 2018-07-31 at 17:48 +0200, Simone Tripodi 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 Looks good now, thanks! > > > > > > 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 Skipping properties in an arbitrary manner should also be useful, so it would be great to add that. > > > > 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 Ok. > > > > > > 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 am not opposed to that, of course. You might also want to check if Felix want to host it and also use it for their own docs, but it's entirely up to you. The Felix advantage is it potentially gathers non-Sling contributors which could focus to contribute to this tool. Being a Sling-hosted tool already sends the message that it's aimed for Sling only. But again - your choice. And also the technical questions/discussions are not meant as checkmarks for inclusion, the contribution is welcome as long as it builds and passes the license checks :-) > > 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? Depends. If this contribution was intended from the beginning to be donated to the ASF you can - as a Sling committer - add it to the Sling whiteboard ( see also [1] ). If the contribution was developed for usage by your employer and is now being open sourced then you need to provide a software grant ( see [2] ) and I will help manage this process. Thanks, Robert [1]: https://cwiki.apache.org/confluence/display/SLING/Using+Git+with+Sling [2]: https://www.apache.org/foundation/how-it-works/legal.html#incoming-code
