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.
| 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."?
There was a problem hiding this comment.
why was this marked as resolved?
|
|
||
| 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?
There was a problem hiding this comment.
I think it makes sense as it is. A VoiceGuildChannel is directly an IVoiceGuildChannel, just not sub-specified into any other voice channel type.
There was a problem hiding this comment.
VoiceGuildChannel is a specific channel type. There are VoiceGuildChannel and StageGuildChannel, both inherit after IVoiceGuildChannel. I think there should at least be something indicating that it is the standard voice channel. I think the current doc will be confusing, because people won't know IVoiceGuildChannel may be a stage channel.
| [JsonPropertyName("create_timestamp")] | ||
| public DateTimeOffset? CreateTimestamp { get; set; } |
There was a problem hiding this comment.
I am not sure this makes sense. Thread create timestamp can be easily retrieved from its ID I believe. Also I think NetCord uses a convention so that it should be named CreatedAt if we really want to introduce this.
| [JsonPropertyName("team_id")] | ||
| public ulong TeamId { get; set; } | ||
|
|
||
| /// <summary> | ||
| /// Specifies a <see cref="SharedClientTheme"/>'s base theme. | ||
| /// </summary> | ||
| public enum BaseTheme : byte |
There was a problem hiding this comment.
I think just BaseTheme is too vague. Maybe something like this?
| public enum BaseTheme : byte | |
| public enum SharedClientThemeBase : byte |
|
|
||
| /// <summary> | ||
| /// Name of the upload. | ||
| /// The filename to use for the upload. |
There was a problem hiding this comment.
This is misleading. Uploaded file name is like the key or the ID of a file to send.
| public virtual bool SupportsHttpSerialization => true; | ||
|
|
||
| public virtual HttpContent Serialize() => new StreamContent(GetStream()!); |
There was a problem hiding this comment.
I think these symbols should also have xml docs
| protected Stream? GetStream() | ||
| { | ||
| if (Interlocked.Exchange(ref _read, 1) is 1) | ||
| ThrowAttachmentAlreadySent(); | ||
|
|
||
| return _stream; | ||
| } |
There was a problem hiding this comment.
This symbol should also have xml docs
|
|
||
| /// <summary> | ||
| /// Timestamp of the embed. | ||
| /// Displays time in a format similar to a message timestamp. Located next to the <see cref="Footer"/>. |
There was a problem hiding this comment.
Maybe something like this? I mean the case that an embed may have a timestamp but no footer.
| /// Displays time in a format similar to a message timestamp. Located next to the <see cref="Footer"/>. | |
| /// Displays time in a format similar to a message timestamp. Located next to the <see cref="Footer"/>, if set. |
| /// <summary> | ||
| /// The thread user's <see cref="PartialGuildUser"/> object. | ||
| /// </summary> | ||
|
|
2 participants
No description provided.