Missing and to-remove code samples

[curquiza]

Related to this file only

I ran a script to which code samples are missing and should be removed in this repo
Here is the result

Missing code samples

meilisearch-swift
- 'delete_documents_by_batch_1' not found
- 'get_typo_tolerance_1' not found
- 'update_typo_tolerance_1' not found
- 'reset_typo_tolerance_1' not found
- 'typo_tolerance_guide_1' not found
- 'typo_tolerance_guide_2' not found
- 'typo_tolerance_guide_3' not found
- 'typo_tolerance_guide_4' not found
- 'get_pagination_settings_1' not found
- 'update_pagination_settings_1' not found
- 'reset_pagination_settings_1' not found
- 'get_faceting_settings_1' not found
- 'update_faceting_settings_1' not found
- 'reset_faceting_settings_1' not found
- 'search_parameter_guide_matching_strategy_1' not found
- 'search_parameter_guide_matching_strategy_2' not found
- 'async_guide_canceled_by_1' not found
- 'delete_tasks_1' not found
- 'cancel_tasks_1' not found
- 'swap_indexes_1' not found
- 'multi_search_1' not found
- 'faceted_search_update_settings_1' not found
- 'faceted_search_1' not found
- 'search_parameter_guide_facet_stats_1' not found
- 'get_documents_post_1' not found
- 'delete_documents_by_filter_1' not found
- 'facet_search_1' not found
- 'facet_search_2' not found
- 'facet_search_3' not found
- 'search_parameter_guide_show_ranking_score_1' not found
- 'tenant_token_guide_generate_sdk_1' not found
- 'tenant_token_guide_search_sdk_1' not found

-> this can be due to missing features in this library.

Refer to this file to have the curl example to translate into swift

To remove code samples

The following code samples can be removed because not used in the documentation anymore:

meilisearch-swift
- 'reset_non_separator_tokens_1' not found in documentation
- 'delete_documents_1' not found in documentation
- 'get_task_by_index_1' not found in documentation
- 'documents_guide_add_movie_1' not found in documentation
- 'getting_started_communicating_with_a_protected_instance' not found in documentation
- 'faceted_search_facets_1' not found in documentation

[Sherlouk]

This is an awesome resource, thank you Clem.

Are you able to share the script which was used to generate this list? It might be useful for myself or other contributors in the future.

We should use this as an opportunity to review the existing samples and make sure they're still accurate and in line with what other languages are doing.

For these snippets, would we rather use closure based examples or async/await? async/await is far more readable with less boilerplate, and is what other languages (such as JS) are doing.

Thoughts Clem?

[curquiza]

Hello @Sherlouk

Unfortunately, I cannot share the link to the repo containing the script publically since it's in one of our (rare) private repo of our organization

however, I can copy paste the scripts here (sorry for the ugly bash scripts)

missing-cs-in-integration.sh

#!/bin/bash

# This script checks if code samples are missing on the integration side.

YELLOW_BOLD='\033[1;33m'
RESET_COLOR='\033[0m'
INTEGRATION_CODE_SAMPLES_FILES=(
    'https://raw.githubusercontent.com/meilisearch/meilisearch-dotnet/main/.code-samples.meilisearch.yaml'
    'https://raw.githubusercontent.com/meilisearch/meilisearch-dart/main/.code-samples.meilisearch.yaml'
    'https://raw.githubusercontent.com/meilisearch/meilisearch-go/main/.code-samples.meilisearch.yaml'
    'https://raw.githubusercontent.com/meilisearch/meilisearch-java/main/.code-samples.meilisearch.yaml'
    'https://raw.githubusercontent.com/meilisearch/meilisearch-js/main/.code-samples.meilisearch.yaml'
    'https://raw.githubusercontent.com/meilisearch/meilisearch-php/main/.code-samples.meilisearch.yaml'
    'https://raw.githubusercontent.com/meilisearch/meilisearch-python/main/.code-samples.meilisearch.yaml'
    'https://raw.githubusercontent.com/meilisearch/meilisearch-ruby/main/.code-samples.meilisearch.yaml'
    'https://raw.githubusercontent.com/meilisearch/meilisearch-rust/main/.code-samples.meilisearch.yaml'
    'https://raw.githubusercontent.com/meilisearch/meilisearch-swift/main/.code-samples.meilisearch.yaml'
)

# List of the code samples that are not needed on the integration side (only curl examples in the docs)
NOT_NEEDED_IN_INTEGRATION=(
    # Tenant token guide part without SDK
    'tenant_token_guide_search_no_sdk_1'
    # Updating latest version of Meilisearch guide
    'updating_guide_check_version_new_authorization_header'
    'updating_guide_check_version_old_authorization_header'
    'updating_guide_get_displayed_attributes_old_authorization_header'
    'updating_guide_reset_displayed_attributes_old_authorization_header'
    'updating_guide_create_dump'
    # Not implemented by SDKs
    'get_experimental_features_1'
    'update_experimental_features_1'
)

# List of caode samples that are not in the docs code samples files, and so, don't have curl examples in the docs
# To look for them: search for `_sdk` in the documentation repository.
NOT_IN_DOCS_CODE_SAMPLES_FILE=(
    'tenant_token_guide_generate_sdk_1'
    'tenant_token_guide_search_sdk_1'
    'landing_getting_started_1' # Use in the landing, not in the docs
)

# Function to check if a code-sample exists in a file
check_code_sample_in_file() {
    local code_sample_id="$1"
    local file="$2"
    local integration_name="$3"


    # Check if code_sample_id is in the NOT_NEEDED_IN_INTEGRATION
    if [[ " ${NOT_NEEDED_IN_INTEGRATION[@]} " =~ " $code_sample_id " ]]; then
        return 0
    fi

    # Check if integration_name != meilisearch-js and if code_sample_id is equal to `search_get_1`
    # Because only meilisearch-js implements search() method with GET
    if [[ $integration_name != "meilisearch-js" ]] && [[ $code_sample_id == "search_get_1" ]]; then
        return 0
    fi

    grep -qF "$code_sample_id" "$file"
}

# Download the documentation code samples file
docs_code_samples_file="docs-code-samples.yaml"
curl -s -o "$docs_code_samples_file" 'https://raw.githubusercontent.com/meilisearch/documentation/main/.code-samples.meilisearch.yaml'

echo 'You can add the following code samples to the integration repositories:'
echo "⚠️  Check the related feature to the code sample is well implemented into the corresponding SDK."
echo ''

# Loop through each URL in INTEGRATION_CODE_SAMPLES_FILES
for url in "${INTEGRATION_CODE_SAMPLES_FILES[@]}"; do
    # Extract the integration name from the URL (e.g., meilisearch-dotnet)
    integration_name=$(echo "$url" | awk -F'/' '{print $5}')
    printf "${YELLOW_BOLD}$integration_name${RESET_COLOR}\n"

    # Download the file
    integration_code_sample_file="integration_code_samples.yaml"
    curl -s -o "$integration_code_sample_file" "$url"

    # Check if code-sample in docs_code_samples_file exists in integration_code_samples
    while IFS= read -r line; do
        code_sample_id=$(echo "$line" | awk -F':' '{print $1}')
        if ! check_code_sample_in_file "$code_sample_id" "$integration_code_sample_file" "$integration_name"; then
            echo "- '$code_sample_id' not found"
        fi
    done < <(grep '|-$' "$docs_code_samples_file")

    # Check if code-sample not present in the code-sample docs file is well present in the integration code samples file
    for code_sample in "${NOT_IN_DOCS_CODE_SAMPLES_FILE[@]}"; do
        if ! check_code_sample_in_file "$code_sample" "$integration_code_sample_file" "$integration_name"; then
            echo "- '$code_sample' not found"
        fi
    done

    # Delete the downloaded integration file
    rm "$integration_code_sample_file"
done

# Delete the downloaded documentation code samples file
rm -f "$docs_code_samples_file"

useless-cs-in-integration.sh

#!/bin/bash

# This script checks if there are code samples on integration side that are not used by the Meilisearch documentation.

BLUE_BOLD='\033[1;34m'
RESET_COLOR='\033[0m'
INTEGRATION_CODE_SAMPLES_FILES=(
    'https://raw.githubusercontent.com/meilisearch/meilisearch-dotnet/main/.code-samples.meilisearch.yaml'
    'https://raw.githubusercontent.com/meilisearch/meilisearch-dart/main/.code-samples.meilisearch.yaml'
    'https://raw.githubusercontent.com/meilisearch/meilisearch-go/main/.code-samples.meilisearch.yaml'
    'https://raw.githubusercontent.com/meilisearch/meilisearch-java/main/.code-samples.meilisearch.yaml'
    'https://raw.githubusercontent.com/meilisearch/meilisearch-js/main/.code-samples.meilisearch.yaml'
    'https://raw.githubusercontent.com/meilisearch/meilisearch-php/main/.code-samples.meilisearch.yaml'
    'https://raw.githubusercontent.com/meilisearch/meilisearch-python/main/.code-samples.meilisearch.yaml'
    'https://raw.githubusercontent.com/meilisearch/meilisearch-ruby/main/.code-samples.meilisearch.yaml'
    'https://raw.githubusercontent.com/meilisearch/meilisearch-rust/main/.code-samples.meilisearch.yaml'
    'https://raw.githubusercontent.com/meilisearch/meilisearch-swift/main/.code-samples.meilisearch.yaml'
)

STILL_NEEDED_IN_INTEGRATION=(
    'landing_getting_started_1'
)

# Function to check if a code-sample exists in a file
check_code_sample_in_repo() {
    local code_sample_id="$1"
    local repository_name="$2"

    # Check if code_sample_id is in the STILL_NEEDED_IN_INTEGRATION,
    # So if the code sample should not be removed
    if [[ " ${STILL_NEEDED_IN_INTEGRATION[@]} " =~ " $code_sample_id " ]]; then
        return 0
    fi

    grep -qr --include=\*.{mdx,yml,yaml} "$code_sample_id" $repository_name/*
}

# Download documentation repository
# Cannot used the code samples repository some code samples are not always in the code samples file
repository_url="https://github.com/meilisearch/documentation"
repository_name=$(basename "$repository_url")
git clone --quiet $repository_url

echo 'You can remove the following code samples from the integration repositories:'
echo "⚠️  Check twice there is no typo in the code sample or if the code sample has been renamed."
echo ''

# Loop through each URL in INTEGRATION_CODE_SAMPLES_FILES
for url in "${INTEGRATION_CODE_SAMPLES_FILES[@]}"; do
    # Extract the integration name from the URL (e.g., meilisearch-dotnet)
    integration_name=$(echo "$url" | awk -F'/' '{print $5}')
    printf "${BLUE_BOLD}$integration_name${RESET_COLOR}\n"

    # Download the file
    integration_code_sample_file="integration_code_samples.yaml"
    curl -s -o "$integration_code_sample_file" "$url"

    # Check if each code-sample in integration_code_samples exists in docs_code_samples
    while IFS= read -r line; do
        code_sample_id=$(echo "$line" | awk -F':' '{print $1}')
        if ! check_code_sample_in_repo "$code_sample_id" "$repository_name"; then
            echo "- '$code_sample_id' not found in documentation"
        fi
    done < <(grep '|-$' "$integration_code_sample_file")

    # Delete the downloaded integration file
    rm "$integration_code_sample_file"
done

# Delete the downloaded documentation repository
rm -rf "$repository_name"

For these snippets, would we rather use closure based examples or async/await? async/await is far more readable with less boilerplate, and is what other languages (such as JS) are doing.

For this question, I rely on you and the community.
None of Meili developers are swift developers, so we started creating code sample based on what we know, but no strongly opinion on this.
Feel free to update them to reflect what the Swift community would expect. We can change them easily anyway if we get any feedback in the future.