Edits to text in API Conventions docs

[dmeiss]

Minor edits to phrasing, punctuation, capitalization, and formatting.

[elasticmachine]

Pinging @elastic/es-core-infra

[danielmitterdorfer]

@elasticmachine test this please

[danielmitterdorfer]

Thanks for these fixes @dmeiss. The changes look mostly fine to me but I left one remark about an incorrect multiplier. Can you please remove the "s" multiplier?

[danielmitterdorfer]

The s suffix is not recognized by Elasticsearch (see also

elasticsearch/server/src/main/java/org/elasticsearch/common/unit/SizeValue.java

Lines 170 to 197 in 869de3f

	public static SizeValue parseSizeValue(String sValue) throws ElasticsearchParseException {
	return parseSizeValue(sValue, null);
	}
	public static SizeValue parseSizeValue(String sValue, SizeValue defaultValue) throws ElasticsearchParseException {
	if (sValue == null) {
	return defaultValue;
	}
	long singles;
	try {
	if (sValue.endsWith("k") || sValue.endsWith("K")) {
	singles = (long) (Double.parseDouble(sValue.substring(0, sValue.length() - 1)) * SizeUnit.C1);
	} else if (sValue.endsWith("m") || sValue.endsWith("M")) {
	singles = (long) (Double.parseDouble(sValue.substring(0, sValue.length() - 1)) * SizeUnit.C2);
	} else if (sValue.endsWith("g") || sValue.endsWith("G")) {
	singles = (long) (Double.parseDouble(sValue.substring(0, sValue.length() - 1)) * SizeUnit.C3);
	} else if (sValue.endsWith("t") || sValue.endsWith("T")) {
	singles = (long) (Double.parseDouble(sValue.substring(0, sValue.length() - 1)) * SizeUnit.C4);
	} else if (sValue.endsWith("p") || sValue.endsWith("P")) {
	singles = (long) (Double.parseDouble(sValue.substring(0, sValue.length() - 1)) * SizeUnit.C5);
	} else {
	singles = Long.parseLong(sValue);
	}
	} catch (NumberFormatException e) {
	throw new ElasticsearchParseException("failed to parse [{}]", e, sValue);
	}
	return new SizeValue(singles, SizeUnit.SINGLE);
	}

) so this needs to be an empty string.

[dmeiss]

Made requested changes. Have a question though about how that empty string should be represented. It’s currently `` but I’m wondering if it should be “” instead.

[danielmitterdorfer]

Have a question though about how that empty string should be represented. It’s currently `` but I’m wondering if it should be “” instead.

On second thought we should just remove the entire line. I doubt that it helps anybody if we document that if no multiplier is specified, we treat the value as is. I think this is expected behavior anyway.

[dmeiss]

I agree. Would you like me to go ahead & remove it?

[dmeiss]

Went ahead & removed the "single" line

[danielmitterdorfer]

Thanks! Looks good to me.

[danielmitterdorfer]

@elasticmachine test this please