On Tue, May 15, 2018 at 01:25:48PM +0300, Jani Nikula wrote: > On Tue, 15 May 2018, Luc Van Oostenryck <luc.vanoostenryck@xxxxxxxxx> wrote: > > The real question to me is "which parts are mistakes and which are not?" > > but I'm all in favor of simplicity. I think I'll begin to document the > > documentation syntax. > > I'll offer my opinion, but feel free to dump it to /dev/null. ;) > > IMHO the lesson from kernel-doc + Sphinx is to resist adding layers of > syntax sugar before the rst parsing (*). If you use Sphinx, defer as > much as possible to Sphinx. Do the minimal @tag conversions you think > are helpful, but don't add more before you actually see demand, and the > rst alternative is unnecessarily clunky. I think this is especially true > in your case where you can relatively easily modify the parser and the > comments in lockstep. It's not a big deal to add features and convert > later on as needed, but only if really needed. > > Just like the comment block style, only support one tag style, whether > it's kernel-doc @foo:, javadoc @param foo, or doxygen \param foo. Keep > it simple, and your codebase uniform. I think it's a good advice and goes in the direction I want to go but a refresh or another opinion from someone having some previous experience is always good to have. Thank you, -- Luc -- To unsubscribe from this list: send the line "unsubscribe linux-sparse" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
