1581202 - Convert interface comments to jsdoc

Status: RESOLVED FIXED

(Chat Core :: General, task)

Description

[Patrick Cloke [:clokep]]

(In reply to Magnus Melin [:mkmelin] from bug 1557506, comment #2)

::: chat/components/public/imIConversationsService.idl
@@ +93,5 @@

[scriptable, uuid(3f88cc5c-6940-4eb5-a576-c65770f49ce9)]
interface imIMessage: prplIMessage {

• attribute boolean cancelled;
• // Holds the sender color for Chats.
• // Empty string by default, it is set by the conversation binding.

For these, please update to jsdoc style documentation comments. /** */

We talked about this on IRC and I'm filing this as a follow-up.

Magnus also gave this as an example:

https://searchfox.org/comm-central/source/mailnews/base/public/nsIMsgKeyArray.idl#28-31

Docs available at https://jsdoc.app/

Comment 1

[Patrick Cloke [:clokep]]

Attachment: Patch v1

This is a pretty mechanical conversation with a few extra bits added.

Comment 2

[Magnus Melin [:mkmelin]]

Comment on attachment 9093138 [details] [diff] [review]
Patch v1

Review of attachment 9093138 [details] [diff] [review]:
-----------------------------------------------------------------

::: chat/components/public/imITagsService.idl
@@ +60,1 @@
>    Array<imITag> getTags();

Would add an empty line before each new   /**
Could also switch to @returns

::: chat/components/public/prplIConversation.idl
@@ +49,5 @@
>    void sendMsg(in AUTF8String aMsg);
>  
> +  /**
> +   * Preprocess messages before they are sent (eg. split long messages).
> +   * Can return null if no changes are to be made.

would be preferable to use @returns to document it

@returns the messages, or null if no changes are to be made

::: chat/components/public/prplIMessage.idl
@@ +71,5 @@
> +   * The first action will be the 'default' and may be performed
> +   * automatically when the message is double clicked.
> +   * For example, 'Reply' is usually a good default action.
> +   *
> +   * @returns an array of prplIMessageAction

@returns prplIMessageAction[]

Comment 3

[Patrick Cloke [:clokep]]

Attachment: Patch v2

Updates the patch with the comments from Magnus.

Comment 4

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/comm-central/rev/6f78a5f43bcd
Convert interface comments to jsdoc for chat. r=mkmelin