¿Cómo puedo expresar esto de manera más clara o concisa?

Estoy documentando un bloque de código de computadora y me gustaría que sea claro y conciso. Estoy describiendo una función que completa un campo en una pantalla de entrada de usuario. Aquí está mi mejor oportunidad, pero todavía parece confuso porque 'en el', 'en el', 'para un' parecen muchas preposiciones para una oración.

This function returns the WINGNUT_SELLER_CODE that appears in the 'Vendor' field  
on the 'THREADED_NUTS' screen for a given NUT_ID.

Preguntas:
[1] ¿Cómo puedo reescribir esto para que sea más fácil de entender?
[2] ¿Qué pasa con 'eso aparece' frente a 'que aparece' cuando debo usar 'eso' y 'cuál'?

¿Son WINGNUT_SELLER_CODE y NUT_ID valores de retorno/parámetros de función? Si es así, son sustantivos casi propios y deberías tratarlos como tales. ¿Qué pasa con THREADED_NUTS? ¿Podemos ver la firma de la función?
Sí, wingnut_seller_code y nut_id son parámetros de retorno/entrada respectivamente. Threaded_nuts es el nombre del formulario. Aquí está la función de firma de función f_get_vend_code (v_nut_id varchar2) return varchar2;
Tal vez si mostraras un diagrama además de la explicación, sería más claro, por ejemplo, una forma que represente la función, con flechas para los valores de entrada y salida.
Esta es una pregunta más antigua. Ha sido golpeado por el sistema porque ha sido reetiquetado, según esta meta publicación. Además, las solicitudes de revisión o crítica de una sola oración normalmente se cierran aquí, pero esto ya se ha preguntado y respondido.

Respuestas (4)

¿Quizás dividirlo en dos oraciones?

Cuando envía a esta función un NUT_ID, devuelve un WINGNUT_SELLER_CODE. Este código es de la pantalla 'THREADED_NUTS' en el campo 'Vendor'.

Casi siempre uso "eso". (Todos los editores que he encontrado parecen decididos a erradicar todos los usos de "cuál".

Hola Lynn. Soy un corrector de estilo que lamenta profundamente la pérdida de "cuál" frente a las cláusulas dependientes adecuadas. Cambiaría todos esos "eso" de nuevo a "cuál" si pudiera. :)
¡Decir ah! Sabía que algunas de mis preguntas tenían que ser correctas, no podía equivocarme todas las veces. :)

Editado en base a los comentarios:

Dada la siguiente declaración de función:

f_get_vend_code (v_nut_id varchar2) devuelve varchar2;

Yo escribiría la descripción de la siguiente manera:

Esta función toma una ID de nuez (NUT_ID) y devuelve el código de vendedor del proveedor (WINGNUT_SELLER_CODE) para este formulario. Si NUT_ID no está configurado (bla, bla, bla). Si la función no puede encontrar un ID de vendedor válido (hace algo).

Nota: estoy usando expresiones idiomáticas de Java porque esas son con las que estoy familiarizado. Supongo que "toma (un parámetro)" y "devoluciones" también son significativos para su audiencia; debe verificarlo leyendo otra documentación de la API para este idioma. También asumo que los valores que usó originalmente, por ejemplo, NUT_ID, son significativos aunque no aparezcan en la firma; si ese no es el caso, los omitiría en la descripción.

También tenga en cuenta que fui más allá de su pregunta original para cubrir los parámetros no válidos y las condiciones de error. La buena documentación de la API va más allá de lo que pueden obtener con solo leer la firma y les dice lo que no podrían averiguar de otra manera.

Intentar

Para un NUT_ID dado, esta función proporciona el WINGNUT_SELLER_CODE que llena el campo 'Vendor' en la pantalla 'THREADED_NUTS'.

tu comentario original es

Esta función devuelve el WINGNUT_SELLER_CODE que aparece en el campo 'Vendor'
en la pantalla 'THREADED_NUTS' para un NUT_ID determinado.

Dado su comentario a Mónica, me parece que su descripción original va mucho más allá de lo que realmente hace la función. En particular, la función en sí misma no muestra la identificación del vendedor, sino que la devuelve a algún otro código que la muestra. La función f_get_vend_code() en sí misma no interactúa ni con el formulario ni con el campo, por lo que no es necesario mencionarlos.

Si eso es cierto, describa solo lo que hace la función: "Esta función devuelve el código de proveedor para la tuerca identificada por NUT_ID".

Además: el nombre de la función y su parámetro parecen documentación casi suficiente en sí mismos. ¿Podría mejorar esos nombres para que la documentación sea innecesaria? Al menos escriba "vendedor" en lugar de abreviarlo innecesariamente como "vendedor". Si hace eso, ¿qué queda para que la documentación transmita?

¿Cómo puedo expresar esto de manera más clara o concisa?
RespuestasAquíPolítica de privacidad1y, 0v