oliverbooth.dev/OliverBooth/Services/ITutorialService.cs
Oliver Booth a7426b008b
feat: show legacy disqus comments beneath gisqus
No Disqus connection here. I just saved them to DB
2024-05-01 16:47:31 +01:00

124 lines
5.5 KiB
C#

using System.Diagnostics.CodeAnalysis;
using OliverBooth.Data;
using OliverBooth.Data.Blog;
using OliverBooth.Data.Web;
namespace OliverBooth.Services;
/// <summary>
/// Represents a service which can retrieve tutorial articles.
/// </summary>
public interface ITutorialService
{
/// <summary>
/// Gets the articles within a tutorial folder.
/// </summary>
/// <param name="folder">The folder whose articles to retrieve.</param>
/// <param name="visibility">The visibility to filter by. -1 does not filter.</param>
/// <returns>A read-only view of the articles in the folder.</returns>
IReadOnlyCollection<ITutorialArticle> GetArticles(ITutorialFolder folder, Visibility visibility = Visibility.None);
/// <summary>
/// Gets the tutorial folders within a specified folder.
/// </summary>
/// <param name="parent">The parent folder.</param>
/// <param name="visibility">The visibility to filter by. -1 does not filter.</param>
/// <returns>A read-only view of the subfolders in the folder.</returns>
IReadOnlyCollection<ITutorialFolder> GetFolders(ITutorialFolder? parent = null, Visibility visibility = Visibility.None);
/// <summary>
/// Gets a folder by its ID.
/// </summary>
/// <param name="id">The ID of the folder to get</param>
/// <param name="folder">
/// When this method returns, contains the folder whose ID is equal to the ID specified, or
/// <see langword="null" /> if no such folder was found.
/// </param>
/// <returns><see langword="true" /></returns>
ITutorialFolder? GetFolder(int id);
/// <summary>
/// Gets a folder by its slug.
/// </summary>
/// <param name="slug">The slug of the folder.</param>
/// <param name="parent">The parent folder.</param>
/// <returns>The folder.</returns>
ITutorialFolder? GetFolder(string? slug, ITutorialFolder? parent = null);
/// <summary>
/// Gets the full slug of the specified folder.
/// </summary>
/// <param name="folder">The folder whose slug to return.</param>
/// <returns>The full slug of the folder.</returns>
/// <exception cref="ArgumentNullException"><paramref name="folder" /> is <see langword="null" />.</exception>
string GetFullSlug(ITutorialFolder folder);
/// <summary>
/// Gets the full slug of the specified article.
/// </summary>
/// <param name="article">The article whose slug to return.</param>
/// <returns>The full slug of the article.</returns>
/// <exception cref="ArgumentNullException"><paramref name="article" /> is <see langword="null" />.</exception>
string GetFullSlug(ITutorialArticle article);
/// <summary>
/// Returns the number of legacy comments for the specified article.
/// </summary>
/// <param name="article">The article whose legacy comments to count.</param>
/// <returns>The total number of legacy comments.</returns>
int GetLegacyCommentCount(ITutorialArticle article);
/// <summary>
/// Returns the collection of legacy comments for the specified article.
/// </summary>
/// <param name="article">The article whose legacy comments to retrieve.</param>
/// <returns>A read-only view of the legacy comments.</returns>
IReadOnlyList<ILegacyComment> GetLegacyComments(ITutorialArticle article);
/// <summary>
/// Returns the collection of replies to the specified legacy comment.
/// </summary>
/// <param name="comment">The comment whose replies to retrieve.</param>
/// <returns>A read-only view of the replies.</returns>
IReadOnlyList<ILegacyComment> GetLegacyReplies(ILegacyComment comment);
/// <summary>
/// Renders the body of the specified article.
/// </summary>
/// <param name="article">The article to render.</param>
/// <returns>The rendered HTML of the article.</returns>
string RenderArticle(ITutorialArticle article);
/// <summary>
/// Renders the excerpt of the specified article.
/// </summary>
/// <param name="article">The article whose excerpt to render.</param>
/// <param name="wasTrimmed">
/// When this method returns, contains <see langword="true" /> if the excerpt was trimmed; otherwise,
/// <see langword="false" />.
/// </param>
/// <returns>The rendered HTML of the article's excerpt.</returns>
string RenderExcerpt(ITutorialArticle article, out bool wasTrimmed);
/// <summary>
/// Attempts to find an article by its ID.
/// </summary>
/// <param name="id">The ID of the article.</param>
/// <param name="article">
/// When this method returns, contains the article whose ID matches the specified <paramref name="id" />, or
/// <see langword="null" /> if no such article was found.
/// </param>
/// <returns><see langword="true" /> if a matching article was found; otherwise, <see langword="false" />.</returns>
bool TryGetArticle(int id, [NotNullWhen(true)] out ITutorialArticle? article);
/// <summary>
/// Attempts to find an article by its slug.
/// </summary>
/// <param name="slug">The slug of the article.</param>
/// <param name="article">
/// When this method returns, contains the article whose slug matches the specified <paramref name="slug" />, or
/// <see langword="null" /> if no such article was found.
/// </param>
/// <returns><see langword="true" /> if a matching article was found; otherwise, <see langword="false" />.</returns>
bool TryGetArticle(string slug, [NotNullWhen(true)] out ITutorialArticle? article);
}