Documentation Generation

[Skyppid]

One feature that was drastically lacking for this tool was the fact that no documentation is being generated. The information from where it is transpiled is kinda useless compared to explicit explanations what the methods actually invoke and the parameters are.

The changes are absolutely trivial, thus I have not written any tests. We plan on further changes / improvements for our requirements, although not all might make it into the main repository. This improvement I don't want to withhold for the community. It's simple yet useful.

This interface for a receiver:

/// <summary>   Client methods for interaction on active projects.    </summary>
[Receiver]
public interface IActiveProjectHubClient
{
    ///-------------------------------------------------------------------------------------------------
    /// <summary>   Informs the client about a user that joined the current project.    </summary>
    ///
    /// <param name="userInfo"> Information describing the user.    </param>
    /// <param name="testA">    The test a. </param>
    /// <param name="testB">    The test b. </param>
    ///
    /// <returns>   A Task. </returns>
    ///-------------------------------------------------------------------------------------------------
    Task UserJoined(UserInfoDto userInfo, string testA, int testB);

    ///-------------------------------------------------------------------------------------------------
    /// <summary>   Informs the client about a user that left the current project.  </summary>
    ///
    /// <param name="userInfo"> Information describing the user.    </param>
    ///
    /// <returns>   A Task. </returns>
    ///-------------------------------------------------------------------------------------------------
    Task UserLeft(UserInfoDto userInfo);
}

gets transpiled into this interface (namespaces were removed):

/**
* Client methods for interaction on active projects.
*/
export type IActiveProjectHubClient = {
    /**
    * Informs the client about a user that joined the current project.
    * @param userInfo Information describing the user. (Transpiled from ***.UserInfoDto)
    * @param testA The test a. (Transpiled from string)
    * @param testB The test b. (Transpiled from int)
    * @returns A Task. (Transpiled from System.Threading.Tasks.Task)
    */
    userJoined(userInfo: UserInfoDto, testA: string, testB: number): Promise<void>;
    /**
    * Informs the client about a user that left the current project.
    * @param userInfo Information describing the user. (Transpiled from ***.UserInfoDto)
    * @returns A Task. (Transpiled from System.Threading.Tasks.Task)
    */
    userLeft(userInfo: UserInfoDto): Promise<void>;
}

Feel free to merge :)

[nenoNaninu]

Thanks for the PR!

[DingbatDev]

Hi @Skyppid & @nenoNaninu,
This is great... I came here looking to make a suggestion, as it's a bit beyond my capability for now, but looks like all the work is done.
I haven't been able to get this working as yet, even after updating to 1.8.2. So I'm checking through my configuration to make sure I have properly updated the Nuget etc.
I assume there is no configuration or changes required? Once updated it should just replace the "transpiled from" comments with the XMLdocs when available?

[DingbatDev]

OK I answered my own question... yes I was a bit slow and forgot:

dotnet tool update --global TypedSignalR.Client.TypeScript.Generator Tool 'typedsignalr.client.typescript.generator' was successfully updated from version '1.7.6' to version '1.8.2'.

The new JSDocs are brilliant! For me this completes the tool very nicely. Awesome work and thank you!

[DingbatDev]

Followup question - any plans to add XMLdocs for records?

[Skyppid]

Followup question - any plans to add XMLdocs for records?

Not from my side. We don't use this library anymore as it did not work well with how we generate our DTOs for the frontend. I tried modifying the library for a more dynamic approach but since it's partially implemented in another library it was too tedious to achieve and we abandoned it as a whole.

[nenoNaninu]

It is the Tapper's responsibility, not TypedSignalR.Client.TypeScript, to generate JSDoc from the XMLdocs. When I have time, I will add functionality to Tapper.