Re: [I] [MS9] Schema and documentation generation from source code (logging-log4j2)
grobmeier commented on issue #1954: URL: https://github.com/apache/logging-log4j2/issues/1954#issuecomment-2006326517 Looks good to me, thanks for all the hard work! -- 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: notifications-unsubscr...@logging.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
Re: [I] [MS9] Schema and documentation generation from source code (logging-log4j2)
grobmeier closed issue #1954: [MS9] Schema and documentation generation from source code URL: https://github.com/apache/logging-log4j2/issues/1954 -- 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: notifications-unsubscr...@logging.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
Re: [I] [MS9] Schema and documentation generation from source code (logging-log4j2)
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 `` in the description,
since users might **literally** write ``, 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: notifications-unsubscr...@logging.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
Re: [I] [MS9] Schema and documentation generation from source code (logging-log4j2)
vy commented on issue #1954:
URL:
https://github.com/apache/logging-log4j2/issues/1954#issuecomment-1929270262
Great work Piotr! :100: :clap:
Some remarks:
1. I see many pages are hardly filled. Shall we collapse the entire
reference to a single page? WDYT? That is, one page per [Maven] module?
1. Why do some nested components appear as `` while some `...
one Filter element ...`? I was expect the latter to be formatted as ``
too.
1. Looking at
[AsyncAppender](https://logging.staged.apache.org/log4j/3.x/ref/Core/org.apache.logging.log4j.core.appender.AsyncAppender.html),
I cannot see
* if I can provide one or more `AppenderRef`s
* what is the default for a nested component
1. We need to document the `KeyValuePair` component
1. We need to document the `value` field of the `Property` component
> 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?
--
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: notifications-unsubscr...@logging.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
Re: [I] [MS9] Schema and documentation generation from source code (logging-log4j2)
ppkarwasz commented on issue #1954:
URL:
https://github.com/apache/logging-log4j2/issues/1954#issuecomment-1929209213
The descriptions are taken from Javadoc comments, which shows us how many
Javadoc comments are missing.
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.
--
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: notifications-unsubscr...@logging.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
Re: [I] [MS9] Schema and documentation generation from source code (logging-log4j2)
ppkarwasz commented on issue #1954: URL: https://github.com/apache/logging-log4j2/issues/1954#issuecomment-1929200674 I have published a preview of a documentation generated from real data. Interesting pages: * [Configuration](https://logging.staged.apache.org/log4j/3.x/ref/Core/org.apache.logging.log4j.core.config.Configuration.html) the description of the global `` element with links to its possible children, * [Appender](https://logging.staged.apache.org/log4j/3.x/ref/Core/org.apache.logging.log4j.core.Appender.html) and [Layout](https://logging.staged.apache.org/log4j/3.x/ref/Core/org.apache.logging.log4j.core.Layout.html) contain a list of known appenders and layouts, * [RollingFileAppender](https://logging.staged.apache.org/log4j/3.x/ref/Core/org.apache.logging.log4j.core.appender.RollingFileAppender.html): the king of complex components, with heavily nested subcomponents. -- 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: notifications-unsubscr...@logging.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
Re: [I] [MS9] Schema and documentation generation from source code (logging-log4j2)
vy commented on issue #1954: URL: https://github.com/apache/logging-log4j2/issues/1954#issuecomment-1822837910 Note that `XmlSchemaTest` needs to be removed and its functionality should ideally be replaced with a `xml-maven-plugin` validation that can take place at the Maven `validation` phase. -- 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: notifications-unsubscr...@logging.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
Re: [I] [MS9] Schema and documentation generation from source code (logging-log4j2)
ppkarwasz commented on issue #1954: URL: https://github.com/apache/logging-log4j2/issues/1954#issuecomment-1806545825 The plan is to delete all `*.md`, `*.adoc` and other files that describe our components' configuration and put everything into Javadoc. The manual will be split into a Configuration Reference (cf [Tomcat's reference](https://tomcat.apache.org/tomcat-9.0-doc/config/index.html)) and a User Guide (cf. [Tomcat's user guide](https://tomcat.apache.org/tomcat-9.0-doc/index.html)). The latter will only explain how the system works, how to use the different configuration formats (with examples) and will not be encumbered with lots of technical details. The Configuration Reference can even collect documentation from third-party plugin developers, if they embed metadata into their jars (or publish on Maven). -- 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: notifications-unsubscr...@logging.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
Re: [I] [MS9] Schema and documentation generation from source code (logging-log4j2)
jvz commented on issue #1954: URL: https://github.com/apache/logging-log4j2/issues/1954#issuecomment-1806525088 I think I've proposed something along these lines in the past, but it seemed like too much work at the time. However, I love this idea in general. It would be great if we could extract JavaDoc metadata from plugin declarations to help form the documentation. Otherwise, we have a lot of duplicated information about plugins. Might also be useful to include metadata that specifies some sample source files to inline for examples. -- 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: notifications-unsubscr...@logging.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
