Merge extended XML documentation.#389
Conversation
- Added significant amounts of documentation to RestClient, channel and message types, and more. - Added some missing / newly-added properties and JSON objects. - Renamed certain flag values for more consistent styling. - Obsoleted certain deprecated properties. - Added some missing flags.
|
The documentation preview is available at https://preview.netcord.dev/389. |
KubaZ2
left a comment
KubaZ2
left a comment
There was a problem hiding this comment.
Thanks for this huge PR! For now I reviewed everything up to UserActivityFlags.
| namespace NetCord; | ||
|
|
||
| /// <summary> | ||
| /// Represents a thread within a <see cref="AnnouncementGuildChannel"/>. |
There was a problem hiding this comment.
| /// Represents a thread within a <see cref="AnnouncementGuildChannel"/>. | |
| /// Represents a thread within an <see cref="AnnouncementGuildChannel"/>. |
| /// <summary> | ||
| /// Represents a <see cref="GuildThread"/> within a <see cref="ForumGuildChannel"/>. | ||
| /// </summary> | ||
| public partial class ForumGuildThread(JsonChannel jsonModel, RestClient client) : PublicGuildThread(jsonModel, client) | ||
| { | ||
| /// <summary> | ||
| /// The message embedded as the thread's starting point. | ||
| /// </summary> | ||
| public RestMessage Message { get; } = new(jsonModel.Message!, client); | ||
| } |
There was a problem hiding this comment.
ForumGuildThread is only received from RestClient.CreateForumGuildThreadAsync (and its aliases). May be a good idea to mention that. This type is not received via any other mean, forum threads are PublicGuildThreads afaik.
| var jsonCurrentUser = jsonModel.CurrentUser; | ||
| if (jsonCurrentUser is not null) | ||
| CurrentUser = new(jsonCurrentUser); | ||
| CurrentUser = new(jsonCurrentUser ); |
There was a problem hiding this comment.
| CurrentUser = new(jsonCurrentUser ); | |
| CurrentUser = new(jsonCurrentUser); |
| public GuildThreadMetadata Metadata { get; } | ||
|
|
||
| /// <summary> | ||
| /// A minimal <see cref="ThreadUser"/> for the current user, if they have joined the thread. |
There was a problem hiding this comment.
I think this is confusing, is says it is "minimal" ThreadUser but in fact it is just ThreadCurrentUser. Maybe it would be better not to mention ThreadUser at all and just say "A minimal thread user for the current user, if they have joined the thread."?
| /// <summary> | ||
| /// Represents a guild thread of a unresolved type. | ||
| /// </summary> |
There was a problem hiding this comment.
I don't think it makes sense to add xml docs to internal types
| /// <summary> | |
| /// Represents a guild thread of a unresolved type. | |
| /// </summary> |
|
|
||
| namespace NetCord; | ||
|
|
||
| /// <inheritdoc cref="IVoiceGuildChannel"/> |
There was a problem hiding this comment.
It is not the same. VoiceGuildChannel in the classic voice channel. StageGuildChannel is also an IVoiceGuildChannel but it is not a VoiceGuildChannel. I think maybe the xml doc from IVoiceGuildChannel matches VoiceGuildChannel and IVoiceGuildChannel should have a separate xml doc explaining that it is a generic channel type?
| public interface IInteractionChannel : IEntity, ISpanFormattable | ||
| { | ||
| /// <summary> | ||
| /// The chan |
|
|
||
| namespace NetCord; | ||
|
|
||
| /// <inheritdoc cref="IUnknownChannel"/> |
There was a problem hiding this comment.
No need to document internal types I think
| /// <inheritdoc cref="IUnknownChannel"/> |
|
|
||
| namespace NetCord; | ||
|
|
||
| /// <inheritdoc cref="IUnknownGuildChannel"/> |
There was a problem hiding this comment.
No need to document internal types I think
| /// <inheritdoc cref="IUnknownGuildChannel"/> |
| namespace NetCord.Gateway; | ||
|
|
||
| /// <summary> | ||
| /// Flags about an activity's state. Not current documented. |
There was a problem hiding this comment.
I think the "Not current documented." shouldn't be in the docs.
| /// Flags about an activity's state. Not current documented. | |
| /// Flags about an activity's state. |
2 participants
No description provided.