You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@lucene.apache.org by GitBox <gi...@apache.org> on 2022/12/16 18:34:18 UTC
[GitHub] [lucene] epotyom opened a new pull request, #12025: Issue #11582 Update Faceting user guide
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-unsubscribe@lucene.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene] rmuir commented on pull request #12025: Issue #11582 Update Faceting user guide
Posted by GitBox <gi...@apache.org>.
rmuir commented on PR #12025:
URL: https://github.com/apache/lucene/pull/12025#issuecomment-1358049032
I'm not familiar enough with the new snippet support to know. I've only glanced at the JEP.
It seemed interesting to me for these cases, but at the same time I don't understand the level of compile-time safety that they have.
At the same time, for demo module we already have a method for compile-time safety of examples that doesn't rely upon this new `@snippet`. See IndexFiles/SearchFiles where we simply include the source code in the javadocs:
https://lucene.apache.org/core/9_4_2/demo/index.html
https://lucene.apache.org/core/9_4_2/demo/src-html/org/apache/lucene/demo/IndexFiles.html
I'd say, if anything the `@snippet` might be something to defer to later. it would make it easier for me to integrate this change. Currently I wouldn't be happy about turning off ECJ checks on javadocs, passing hardcoded org.apache.lucene.demo stuff to every lucene module, generating radically different docs depending on JDK version, etc. It makes things a lot more complicated.
--
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-unsubscribe@lucene.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene] rmuir commented on pull request #12025: Issue #11582 Update Faceting user guide
Posted by GitBox <gi...@apache.org>.
rmuir commented on PR #12025:
URL: https://github.com/apache/lucene/pull/12025#issuecomment-1361698706
Thank you @epotyom for this! I'll backport to 9.5.
--
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-unsubscribe@lucene.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene] rmuir merged pull request #12025: Issue #11582 Update Faceting user guide
Posted by GitBox <gi...@apache.org>.
rmuir merged PR #12025:
URL: https://github.com/apache/lucene/pull/12025
--
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-unsubscribe@lucene.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene] epotyom commented on pull request #12025: Issue #11582 Update Faceting user guide
Posted by GitBox <gi...@apache.org>.
epotyom commented on PR #12025:
URL: https://github.com/apache/lucene/pull/12025#issuecomment-1361631708
> At the same time, for demo module we already have a method for compile-time safety of examples that doesn't rely upon this new `@snippet`. See IndexFiles/SearchFiles where we simply include the source code in the javadocs
There is a check that referenced `region`s exist in the source file. And the regions support is the only benefit really compared to links to source code as in your IndexFiles/SearchFiles example, because you don't need to scroll through source files to find an example referenced. But it's true that it doesn't beat disadvantages that you listed. Updated the pull request to link to source files instead of using snippets.
--
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-unsubscribe@lucene.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene] epotyom closed pull request #12025: Issue #11582 Update Faceting user guide
Posted by GitBox <gi...@apache.org>.
epotyom closed pull request #12025: Issue #11582 Update Faceting user guide
URL: https://github.com/apache/lucene/pull/12025
--
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-unsubscribe@lucene.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene] rmuir commented on pull request #12025: Issue #11582 Update Faceting user guide
Posted by GitBox <gi...@apache.org>.
rmuir commented on PR #12025:
URL: https://github.com/apache/lucene/pull/12025#issuecomment-1355487624
From maintenance perspective, I think it would be better to bump the minimum java requirement (e.g. to 19) than to only process the `@snippet` on certain newer JDKs, and produce different-looking docs on 17/18.
A big problem is that github actions etc are using java 17 (the minimum version), so nothing would really be testing the snippets across code changes and they could get broken easily.
--
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-unsubscribe@lucene.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene] epotyom commented on pull request #12025: Issue #11582 Update Faceting user guide
Posted by GitBox <gi...@apache.org>.
epotyom commented on PR #12025:
URL: https://github.com/apache/lucene/pull/12025#issuecomment-1357980091
>
--
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-unsubscribe@lucene.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene] epotyom commented on pull request #12025: Issue #11582 Update Faceting user guide
Posted by GitBox <gi...@apache.org>.
epotyom commented on PR #12025:
URL: https://github.com/apache/lucene/pull/12025#issuecomment-1362544604
> Thank you @epotyom for this! I'll backport to 9.5.
Thank you!
--
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-unsubscribe@lucene.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
[GitHub] [lucene] epotyom commented on pull request #12025: Issue #11582 Update Faceting user guide
Posted by GitBox <gi...@apache.org>.
epotyom commented on PR #12025:
URL: https://github.com/apache/lucene/pull/12025#issuecomment-1358036804
> From maintenance perspective, I think it would be better to bump the minimum java requirement (e.g. to 19) than to only process the `@snippet` on certain newer JDKs, and produce different-looking docs on 17/18.
>
> A big problem is that github actions etc are using java 17 (the minimum version), so nothing would really be testing the snippets across code changes and they could get broken easily.
Thank you for the reply! Do you think it worth changing the minimum requirement just for this change?
I can also look into implementing some basic `@snippet` support in java 17 as a [javadoc Taglet](https://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/taglet/overview.html) and we can use it until there are more reasons to change the requirements, what do you think?
--
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-unsubscribe@lucene.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org