Documentazione: che cosa è "appropriato" quando si esprime un intervallo valido per un parametro?

Se questo è il tuo intervallo valido, dovrei semplicemente usare un byte (firmato) e lasciare che il compilatore lo faccia rispettare: -)

Altrimenti, qualsiasi modulo di documentazione di cui sei soddisfatto, che sia intuitivamente comprensibile dal lettore, ed è tecnicamente corretto e chiaro, va bene. Vado per qualcosa di breve e universalmente comprensibile come (0 < = arg < = 255).

Un'altra cosa da considerare è che cosa può causare un valore fuori limite? Nella maggior parte dei casi, un valore fuori intervallo causerà un effetto (un errore di asserzione, un arresto anomalo, un'eccezione, un codice di errore, un comportamento indefinito?) Quindi potresti voler documentare cosa accadrà se viene fornito un input OOR. Dopotutto, stai documentandolo in modo che i chiamanti sappiano come usarlo e cosa potrebbe accadere se ottengono qualcosa di sbagliato.

Usa i costrutti che ti dà la lingua, perché è una buona combinazione di essere concisi e comprensibili (per il tuo pubblico, che sono i programmatori). Quindi per Python, scriverebbe "0 < = arg < = 255".

Vorrei cercare il codice sorgente delle librerie principali nella tua lingua. Ecco un esempio di metodo Substring della classe String in c #:

Public Function Substring(startIndex As Integer) As String
     Member of System.String
Summary:
Retrieves a substring from this instance. The substring starts at a specified character position.

Parameters:
startIndex: The zero-based starting character position of a substring in this instance.

Return Values:
A string that is equivalent to the substring that begins at startIndex in this instance, or System.String.Empty if startIndex is equal to the length of this instance.

Exceptions:
System.ArgumentOutOfRangeException: startIndex is less than zero or greater than the length of this instance.