第五周代码注释

comments/admin.py

@@ -1,47 +1,64 @@
 from django.contrib import admin
 from django.urls import reverse
-from django.utils.html import format_html
-from django.utils.translation import gettext_lazy as _
+from django.utils.html import format_html  # 用于安全渲染HTML内容
+from django.utils.translation import gettext_lazy as _  # 用于国际化翻译
 
 
+# 自定义批量操作：禁用选中的评论
 def disable_commentstatus(modeladmin, request, queryset):
+    # 将选中评论的is_enable字段批量更新为False
     queryset.update(is_enable=False)
 
 
+# 自定义批量操作：启用选中的评论
 def enable_commentstatus(modeladmin, request, queryset):
+    # 将选中评论的is_enable字段批量更新为True
     queryset.update(is_enable=True)
 
 
+# 为批量操作设置显示名称（支持国际化）
 disable_commentstatus.short_description = _('Disable comments')
 enable_commentstatus.short_description = _('Enable comments')
 
 
 class CommentAdmin(admin.ModelAdmin):
-    list_per_page = 20
+    """评论模型的Admin配置类，控制后台评论管理界面的展示和功能"""
+
+    list_per_page = 20  # 每页显示20条评论
     list_display = (
-        'id',
-        'body',
-        'link_to_userinfo',
-        'link_to_article',
-        'is_enable',
-        'creation_time')
-    list_display_links = ('id', 'body', 'is_enable')
-    list_filter = ('is_enable',)
-    exclude = ('creation_time', 'last_modify_time')
-    actions = [disable_commentstatus, enable_commentstatus]
+        'id',  # 评论ID
+        'body',  # 评论内容
+        'link_to_userinfo',  # 自定义字段：评论作者的链接
+        'link_to_article',  # 自定义字段：评论所属文章的链接
+        'is_enable',  # 是否启用
+        'creation_time'  # 创建时间
+    )
+    list_display_links = ('id', 'body', 'is_enable')  # 列表中可点击跳转编辑页的字段
+    list_filter = ('is_enable',)  # 右侧筛选器：按是否启用筛选
+    exclude = ('creation_time', 'last_modify_time')  # 编辑页排除的字段（不允许手动修改）
+    actions = [disable_commentstatus, enable_commentstatus]  # 注册批量操作
 
     def link_to_userinfo(self, obj):
+        """自定义列表字段：生成评论作者的后台编辑页链接"""
+        # 获取作者模型的app标签和模型名称（用于反向生成URL）
         info = (obj.author._meta.app_label, obj.author._meta.model_name)
+        # 反向生成作者模型的编辑页URL
         link = reverse('admin:%s_%s_change' % info, args=(obj.author.id,))
+        # 渲染为HTML链接（优先显示昵称，无昵称则显示邮箱）
         return format_html(
             u'<a href="%s">%s</a>' %
-            (link, obj.author.nickname if obj.author.nickname else obj.author.email))
+            (link, obj.author.nickname if obj.author.nickname else obj.author.email)
+        )
 
     def link_to_article(self, obj):
+        """自定义列表字段：生成评论所属文章的后台编辑页链接"""
+        # 获取文章模型的app标签和模型名称
         info = (obj.article._meta.app_label, obj.article._meta.model_name)
+        # 反向生成文章模型的编辑页URL
         link = reverse('admin:%s_%s_change' % info, args=(obj.article.id,))
-        return format_html(
-            u'<a href="%s">%s</a>' % (link, obj.article.title))
+        # 渲染为HTML链接（显示文章标题）
+        return format_html(u'<a href="%s">%s</a>' % (link, obj.article.title))
 
+    # 为自定义字段设置显示名称（支持国际化）
     link_to_userinfo.short_description = _('User')
-    link_to_article.short_description = _('Article')
+    link_to_article.short_description = _('Article')

comments/apps.py

@@ -2,4 +2,12 @@ from django.apps import AppConfig
 
 
 class CommentsConfig(AppConfig):
-    name = 'comments'
+    """
+    Django应用配置类，用于定义"comments"应用的元数据和配置
+
+    Django中每个应用都需要通过继承AppConfig类来声明应用信息，
+    该类会在项目启动时被Django自动加载，用于初始化应用相关设置
+    """
+    # 应用的唯一标识名称，必须与应用目录名一致，用于Django识别和管理该应用
+    # 在settings.py的INSTALLED_APPS中注册时，通常使用这个名称（如'comments'）
+    name = 'comments'

comments/templatetags/comments_tags.py

@@ -1,5 +1,6 @@
 from django import template
 
+# 注册模板标签库，用于在Django模板中加载自定义标签
 register = template.Library()
 
 
@@ -8,23 +9,35 @@ def parse_commenttree(commentlist, comment):
     """获得当前评论子评论的列表
         用法: {% parse_commenttree article_comments comment as childcomments %}
     """
+    # 存储所有子评论的列表（包括嵌套子评论）
     datas = []
 
+    # 递归函数：用于遍历评论的所有后代评论
     def parse(c):
+        # 筛选出当前评论c的直接子评论（已启用状态）
+        # commentlist是评论查询集，通过parent_comment关联父评论
         childs = commentlist.filter(parent_comment=c, is_enable=True)
+        # 遍历每个直接子评论
         for child in childs:
+            # 将子评论添加到结果列表
             datas.append(child)
+            # 递归处理子评论的子评论（深度优先遍历）
             parse(child)
 
+    # 从当前评论开始递归解析所有子评论
     parse(comment)
+    # 返回收集到的所有子评论列表
     return datas
 
 
 @register.inclusion_tag('comments/tags/comment_item.html')
 def show_comment_item(comment, ischild):
-    """评论"""
+    """评论渲染标签：用于在模板中展示单个评论项"""
+    # 根据是否为子评论设置层级深度（可能用于前端样式区分，如缩进）
+    # 子评论depth=1，顶级评论depth=2（这里的数值可根据实际样式需求调整）
     depth = 1 if ischild else 2
+    # 向模板传递变量：评论对象和层级深度
     return {
-        'comment_item': comment,
-        'depth': depth
-    }
+        'comment_item': comment,  # 评论对象，包含作者、内容、时间等信息
+        'depth': depth  # 层级深度，用于前端渲染样式
+    }