The proper use of 'e.g.' and 'i.e.' are confusing and reportedly are one of the most frequent sources of mistakes editors see in technical writing/documentation. Find the patch attached.

Comments

rajeshwari10 created an issue. See original summary.

rajeshwari10’s picture

Status: Active » Needs review
StatusFileSize
new29.14 KB
borisson_’s picture

Status: Needs review » Needs work

Can you please make sure that these changes don't break the 80 chars rule?

rajeshwari10’s picture

Status: Needs work » Needs review
StatusFileSize
new31.46 KB

I have made changes. So,that the doc wont break 80 chars rule.

Please Review.

Thanks!!

borisson_’s picture

Status: Needs review » Needs work

The 80 cols rule also applies for punctuation. Also please provide an interdiff: https://www.drupal.org/documentation/git/interdiff

  1. +++ b/search_api.theme.inc
    @@ -394,7 +394,7 @@ function theme_search_api_index($variables) {
    +      // @todo Add a cleaner way for doing this (that is, skipping preprocessing).
    

    80 cols.

  2. +++ b/src/Plugin/ConfigurablePluginInterface.php
    @@ -43,7 +43,7 @@ interface ConfigurablePluginInterface extends PluginInspectionInterface, Derivat
    +   *   Whether the dependency was successfully removed from the plugin – that is,
    

    80 cols

  3. +++ b/src/Plugin/IndexPluginBase.php
    @@ -20,7 +20,7 @@ abstract class IndexPluginBase extends ConfigurablePluginBase implements IndexPl
    +    // @todo Change key to, for example, '*index', to avoid potential collisions.
    

    80 cols

  4. +++ b/src/Plugin/search_api/processor/Tokenizer.php
    @@ -212,8 +212,8 @@ class Tokenizer extends FieldsProcessorPluginBase {
    +    // searching for for example '20/03/1984' also returns results with
    +    // '20-03-1984' in them.
    

    This is wrong now, I think it should be "for, for example, ". But I'm not sure about the second comma.

  5. +++ b/src/Plugin/views/query/SearchApiQuery.php
    @@ -1115,12 +1115,12 @@ class SearchApiQuery extends QueryPluginBase {
    +   *   negation works on the whole array, not on each contained term individually
    

    80 cols

  6. +++ b/src/Query/ConditionGroupInterface.php
    @@ -26,7 +26,7 @@ interface ConditionGroupInterface extends ConditionSetInterface {
    +   *   Returned by reference so it's possible to, for example, remove conditions.
    

    80 cols.

  7. +++ b/src/Query/QueryInterface.php
    @@ -248,12 +248,12 @@ interface QueryInterface extends ConditionSetInterface {
    +   *   negation works on the whole array, not on each contained term individually
    

    80 cols.

  8. +++ b/tests/src/Kernel/Processor/RenderedItemTest.php
    @@ -153,12 +153,12 @@ class RenderedItemTest extends ProcessorTestBase {
    +      // Test that the value is a string (not, for example, a SafeString object).
    

    80 cols.

rajeshwari10’s picture

Status: Needs work » Needs review
StatusFileSize
new31.64 KB
new7.37 KB

Adding patch and interdiff.

Thanks!!

drunken monkey’s picture

Status: Needs review » Postponed
Related issues: +#2760911: Use of "e.g." and "i.e."

Thanks for creating this issue!

+++ b/search_api.theme.inc
@@ -394,7 +394,8 @@ function theme_search_api_index($variables) {
-      // @todo Add a cleaner way for doing this (i.e., skipping preprocessing).
+      // @todo Add a cleaner way for doing this (that is, skipping
+      // preprocessing).

The second line should be indented with two (additional) spaces.

I also wouldn't think we should keep all those commas – in most cases they aren't needed after "for example", I'd say.

Also, the patch has become outdated and would need to be re-rolled.

"Would" because, more importantly, I'm really not sure we need to do this. While a small matter, it still makes the docs more verbose, using the abbreviations is just handier. And I'd hope this wouldn't be such an impediment to proper understanding of the docs. Even if they are regularly misused, I think reading them is far less error-prone, since you can almost always deduce their meaning from the context.
Nevertheless, I've opened #2760911: Use of "e.g." and "i.e." to discuss this on the coding standards level – if the majority there agrees that this is a problem (no matter whether it actually makes it into the standards), we can still do this. But otherwise, I'd be against it.

drunken monkey’s picture

Issue tags: -documentation Quick fix +Quick fix
drunken monkey’s picture

Status: Postponed » Needs review
StatusFileSize
new16.69 KB
new36.07 KB

"The majority" in this case is just Jennifer Hodgdon, but since I respect her opinion on this, let's do this! (Especially since some of the usage is not just code comments, but user-facing.) We should then also try to not use this anymore in new code we introduce – I hope I manage to think of that.

The attached patch is a re-roll applying to the latest dev version and also re-phrasing a few places according to my (personal) taste. It also fixes a few minor problems next to existing changes.
Please review to see if that covers everything!

Side note:

      $missing_ids = array_reduce(array_map('array_values', $items_by_datasource), 'array_merge', array());

I love this line! It shouts, "I wish I was coding Haskell!"

borisson_’s picture

Status: Needs review » Reviewed & tested by the community

drunken monkey’s picture

Status: Reviewed & tested by the community » Fixed

Thanks for reviewing!
Committed.
Thanks again for this initiative, rajeshwari10!

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.