ppkarwasz commented on issue #1954: URL: https://github.com/apache/logging-log4j2/issues/1954#issuecomment-1929293548
1. Absolutely. It is easier to output a different Asciidoc document per plugin, but it will probably look better as a single page or a couple of pages. 2. This is due to the [FreeMarker template](https://github.com/apache/logging-log4j-tools/blob/main/log4j-docgen/src/test/resources/templates/plugin.ftl) I used. If there is only a single choice of plugin (e.g. `AppenderRef`) it outputs the official name of the plugin, otherwise an expression like `... one Filter element ...`. I would be against using `<Filter/>` in the description, since users might **literally** write `<Filter/>`, but there is a lot of room for improvement in the template, 3. Again, it is a template problem, the data (`multiplicity="*"`) is there, but is not displayed. Regarding default values for nested components, we should provide that data in the Javadoc of the element: there is no way to reliably guess that. 4. All those missing description must be filled by us (e.g. @grobmeier), but we can do it in parallel with code changes to `log4j-docgen`. >> Also the links in the descriptions (which are taken from {@link ...} comments in Javadoc) are usually broken, since the documentation generator currently can not determine the correct link to use. > > What is the plan to address this shortcoming? As far as I understand we can either: - leave some placeholders for links in `plugins.xml` and fill them up with the appropriate link (to our Javadoc, an external Javadoc or our reference manual) during the generation of Asciidoc pages, - or write an Asciidoc macro that does the same during compilation. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
