epotyom opened a new pull request, #12025: URL: https://github.com/apache/lucene/pull/12025
Issue: https://github.com/apache/lucene/issues/11582 The [Facet Userguide](https://lucene.apache.org/core/4_1_0/facet/org/apache/lucene/facet/doc-files/userguide.html) was removed from the package as part of [LUCENE-4894](https://issues.apache.org/jira/browse/LUCENE-4894) with a conclusion that it is hard to keep it updated and that we should maintain javadocs for the relevant classes instead. However, [current facet package overview](https://lucene.apache.org/core/9_3_0/facet/index.html) refers to blog posts that are out of date too. I think it makes sens to redeem the user guide, but we need some mechanisms to make sure the examples in it are maintained. I think there are 2 main cases to take care of: * Links to classes/packages. If we write the user guide as a javadoc, we can make sure the links are relevant by using `@link` tag. * Code snippets. `<pre>` and `<code>` are not ideal, because code inside them is never tested or compiled, so it will be out of date very fast again. Luckily, there is a [tag `@snippet`](https://docs.oracle.com/en/java/javase/18/code-snippet/index.html) added to javadoc recently (JDK18), and it supports inserting code snippets from external files, which can be compiled and tested. We can disable snippet tag and redirect users to source code for older java versions. Next question: where to add it? I don't think javadoc supports adding random doc pages, there is `--overview` option, but I think it wouldn't be very convenient to have user guide inside the [main page of the facet module documentation](https://lucene.apache.org/core/9_3_0/facet/index.html). I think the best place for it is [demo/facet package summary](https://lucene.apache.org/core/9_3_0/demo/org/apache/lucene/demo/facet/package-summary.html). It is currently empty, and it will be convenient to insert code snippets/links to the facet examples from this doc. I have updated the user guide, but I'm not too familiar with faceting yet, so please let me know if something is not accurate. -- 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: issues-unsubscr...@lucene.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org --------------------------------------------------------------------- To unsubscribe, e-mail: issues-unsubscr...@lucene.apache.org For additional commands, e-mail: issues-h...@lucene.apache.org
