Incorporación de documentación de funciones

Power Query generará automáticamente una interfaz de usuario de invocación basada en los argumentos de la función. De forma predeterminada, la interfaz de usuario contiene el nombre de la función y una entrada para cada uno de los parámetros.

De la misma forma, la evaluación del nombre de la función, sin especificar parámetros, muestra información sobre la misma.

Es posible que observe que las funciones integradas habitualmente brindan una mejor experiencia de usuario, con descripciones, información sobre herramientas e incluso valores de ejemplo. Es posible sacar provecho de este mismo mecanismo si se definen metadatos específicos sobre el tipo de función. Aquí se describen los campos de metadatos que usa Power Query y su uso en las extensiones.

Tipos de función

Es posible proporcionar documentación para la función si se definen valores de tipo personalizados. El proceso tiene este aspecto:

1. Defina un tipo para cada uno de los parámetros.
2. Defina un tipo para la función.
3. Añada varios campos Documentation.* al registro de metadatos de tipos.
4. Llame a Value.ReplaceType para la asignación del tipo a la función compartida.

Es posible encontrar más información acerca de los tipos y los valores de metadatos en la especificación Lenguaje M.

El uso de este enfoque permite brindar a la función descripciones y nombres para mostrar, así como parámetros individuales. También se pueden proporcionar valores de ejemplo para los parámetros, así como definir una lista preestablecida de valores (lo que convertirá el control de cuadro de texto predeterminado en una lista desplegable).

La experiencia Power Query recupera la documentación de los valores de metadatos del tipo de función a través de una combinación de llamadas a Value.Type, Type.FunctionParameters y Value.Metadata.

Documentación de funciones

En la tabla a continuación se enumeran los campos de documentación que se pueden establecer en los metadatos de la función. Todos los campos son opcionales.

Campo	Tipo	Detalles
Documentation.Examples	list	Lista de objetos de registro con ejemplo de uso de la función. Solo se muestra como parte de la información de la función. Cada registro debe contener los siguientes campos de texto opcionales: Description, Codey Result.
Documentation.LongDescription	text	Descripción completa respecto a la tarea de la función, que se muestra en la información de la misma.
Documentation.Name	text	Texto que aparece en la parte superior del cuadro de diálogo de invocación de la función.

Documentación de parámetros

En la tabla a continuación se enumeran los campos de documentación que se pueden establecer en los metadatos de los parámetros de función. Todos los campos son opcionales.

Campo	Tipo	Detalles
Documentation.AllowedValues	list	Lista de valores válidos para el parámetro. Si se rellena este campo, la entrada cambiará de un cuadro de texto a una lista desplegable. Observe que esto no impide que un usuario edite la consulta de forma manual para proporcionar valores alternativos.
Documentation.FieldCaption	text	Nombre descriptivo para el parámetro.
Documentation.FieldDescription	text	Descripción que aparece junto al nombre para mostrar.
Documentation.SampleValues	list	Lista de valores de ejemplo que se mostrarán (en forma de texto atenuado) dentro del cuadro de texto.
Format.IsMultiLine	boolean	Permite crear una entrada de más de una línea, por ejemplo, para pegar en consultas nativas.
Format.IsCode	boolean	Da formato al campo de entrada para el código, por lo general con entradas de varias líneas. Utiliza una fuente similar a un código en lugar de la fuente estándar.

Ejemplo básico

El siguiente fragmento de código (y los diálogos obtenidos) procede del ejemplo HelloWorldWithDocs.

[DataSource.Kind="HelloWorldWithDocs", Publish="HelloWorldWithDocs.Publish"]
shared HelloWorldWithDocs.Contents = Value.ReplaceType(HelloWorldImpl, HelloWorldType);

HelloWorldType = type function (
    message as (type text meta [
        Documentation.FieldCaption = "Message",
        Documentation.FieldDescription = "Text to display",
        Documentation.SampleValues = {"Hello world", "Hola mundo"}
    ]),
    optional count as (type number meta [
        Documentation.FieldCaption = "Count",
        Documentation.FieldDescription = "Number of times to repeat the message",
        Documentation.AllowedValues = { 1, 2, 3 }
    ]))
    as table meta [
        Documentation.Name = "Hello - Name",
        Documentation.LongDescription = "Hello - Long Description",
        Documentation.Examples = {[
            Description = "Returns a table with 'Hello world' repeated 2 times",
            Code = "HelloWorldWithDocs.Contents(""Hello world"", 2)",
            Result = "#table({""Column1""}, {{""Hello world""}, {""Hello world""}})"
        ],[
            Description = "Another example, new message, new count!",
            Code = "HelloWorldWithDocs.Contents(""Goodbye"", 1)",
            Result = "#table({""Column1""}, {{""Goodbye""}})"
        ]}
    ];

HelloWorldImpl = (message as text, optional count as number) as table =>
    let
        _count = if (count <> null) then count else 5,
        listOfMessages = List.Repeat({message}, _count),
        table = Table.FromList(listOfMessages, Splitter.SplitByNothing())
    in
        table;

El código da como resultado los cuadros de diálogo siguientes en Power BI.

function_invocation

Información de función

Ejemplo de varias líneas

[DataSource.Kind="HelloWorld", Publish="HelloWorld.Publish"]
shared HelloWorld.Contents =
    let
        HelloWorldType = type function (
            message1 as (type text meta [
                Documentation.FieldCaption = "Message 1",
                Documentation.FieldDescription = "Text to display for message 1",
                Documentation.SampleValues = {"Hello world"},
                Formatting.IsMultiLine = true,
                Formatting.IsCode = true
            ]),
            message2 as (type text meta [
                Documentation.FieldCaption = "Message 2",
                Documentation.FieldDescription = "Text to display for message 2",
                Documentation.SampleValues = {"Hola mundo"},
                Formatting.IsMultiLine = true,
                Formatting.IsCode = false
            ])) as text,
        HelloWorldFunction = (message1 as text, message2 as text) as text => message1 & message2
    in
        Value.ReplaceType(HelloWorldFunction, HelloWorldType);

El código (con la información de publicación asociada, etc.) da como resultado el siguiente diálogo en Power BI. Las nuevas líneas se representarán en el texto con "#(lf)" o "avance de líneas".