How to add documentation to custom functions in Power Query Custom Connector?

[Anonymous]

HI. I'm building a custom connector for Power BI, and I'd like to add documentation to my custom functions. I have read the official documentation and a few blog posts about this. I can't see what is wrong. What I have tried:

section CustomConnector;

// this the function that gets exposed to the UI
[DataSource.Kind="CustomConnector", Publish="CustomConnector.Publish"]
shared CustomConnector.Contents = () =>
    let
        source = Navigation()
    in
        source;

// This is my navigator
Navigation = () =>
    let
      objects = #table(
       {"Name",                "Key",                    "Data",                                                        "ItemKind", "ItemName", "IsLeaf"},{    
       {"Function1",         "GetFunction1",             GetFunction1(),                                                "Table",    "Table",     true}, 
       {"GetFunction2",  "CustomConnector.GetFunction2", (optional artist_id as text) as table => CustomConnector.GetFunction2(artist_id), "Function", "Function",  true}}),
        NavTable = Table.ToNavigationTable(objects, {"Key"}, "Name", "Data", "ItemKind", "ItemName", "IsLeaf") 
    in
        NavTable;

// This is an example of the function I want to provide documentation for
GetFunction2 = (optional artist_id) =>   
    let 
       source = "https://www.example.com/",
       response = Json.Document( Web.Contents ( source, [RelativePath = path & artist_id]) )
    in
       response;

// now the custom type function
GetFunction2Type = type function 
        (             
            optional artist_id as text  
        ) as table meta 
            [
                Documentation.Name = "GetFunction2",
                Documentation.LongDescription = "This function returns a table with details about the artist.",
                Documentation.Examples = 
                {
                    [
                        Description = "This function returns a table with details about the artist.",
                        Code = "GetFunction2(6WCWkB4bsGX2HDsoyaQb6KyL)",
                        Result = "Source = #table(
                                                {
                                                  ""something"",   
                                                  ""something2""   
                                                }, {{},{})"
                    ]
                }
            ];

// This is where I replace the original type for the custom type.
[DataSource.Kind = "CustomConnector"]
shared CustomConnector.GetFunction2 = Value.ReplaceType(GetFunction2 , GetFunction2Type);

// and here is my DataSource.Kind record
CustomConnector = [

    TestConnection = (dataSourcePath) => { "CustomConnector.Navigation" },
    Authentication = [
        OAuth = [
            StartLogin = StartLogin,
            FinishLogin = FinishLogin,
            Refresh = Refresh,
            Logout = Logout
         ]
     ]
];

Important aspect from the docs: "Functions associated with a data source must have the same required function parameters (including name, type, and order). Functions for a specific Data Source Kind can only use credentials associated with that Kind.". I think I understood this. Now here is how this appears on the navigator in Power BI:

This is the same as before I implemented the custom documentation functions. Nothing happened and it is working normally.

Can anyone spot some mistake I'm making? Thank you.

[v-juanli-msft]

Hi @Anonymous 

Is this problem sloved? 

If it is sloved, could you kindly accept it as a solution to close this case?

Best Regards

Maggie

[artemus]

The metadata belongs on the type of the function, not on the value of the function. Use Value.RaplaceType to do this.

[Anonymous]

shared CustomConnector.GetFunction2 = Value.ReplaceType(GetFunction2 , GetFunction2Type);

You mean like this or another way? 

[artemus]

Oh I see, I think the [DataSource.Kind = ...] is overriding the metadata you already have. You should be able to just append it to your current metadata:

[
   DataSource.Kind = "CustomConnector", 
   Documentation.Name = "GetFunction2",
   ...
]
shared CustomConnector.GetFunction2 = GetFunction2

[artemus]

Actually scratch that, just add 

Documentation.Description

to your origional solution

[Anonymous]

I did, but it still doesn't work. I replaced "Documentation.LongDescription" with "Documentation.Description" but it still shows like this:

http://prntscr.com/qahgdr

[artemus · Accepted solution]

Here is a sample of a more complete connector:

    FunctionType = let 
            paramType = type text meta [
                Documentation.FieldCaption = ...
            ],
            t = type function (param as paramType) as table
        in             
t meta [
                Documentation.Description = ...,
                Documentation.DisplayName = ...,
                Documentation.Caption = ...,
                Documentation.Name = ...,
                Documentation.LongDescription = ...,
                Documentation.Examples = {[
                    Description = ...,
                    Code = ...,
                    Result = ...
                ]}
            ],

[Anonymous]

Thank you for the help @artemus. I'm checking that out.