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 have toyed with doing some syntax sugar coating *after* the rst parsing, on the doctrees. For example, changing "foo()" to a reference to function foo documentation if that exists. Alas I've run into some Sphinx related issues in changing the doctrees, and I haven't had the time to solve them. But I think the idea is workable, and it doesn't conflict with rst syntax the way the regexp based changes in kernel-doc do. BR, Jani. (*) In kernel-doc this was unavoidable due to the huge amounts of existing kernel-doc comments that needed to mostly parse about right. -- Jani Nikula, Intel Open Source Technology Center -- 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
