Document the line-number counting behavior (#27386)

Ref #27377

diff --git a/routers/web/repo/view.go b/routers/web/repo/view.go
index 9085bda395f150c66b2df20469e7879b9fc0acdb..657179062736c102ca0c91bc5f197071d4434e6a 100644 (file)
--- a/routers/web/repo/view.go
+++ b/routers/web/repo/view.go
@@ -488,8 +488,13 @@ func renderFile(ctx *context.Context, entry *git.TreeEntry, treeLink, rawLink st
                } else {
                        buf, _ := io.ReadAll(rd)
 
-                       // empty: 0 lines; "a": one line; "a\n": two lines; "a\nb": two lines;
-                       // the NumLines is only used for the display on the UI: "xxx lines"
+                       // The Open Group Base Specification: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html
+                       //   empty: 0 lines; "a": 1 line, 1 incomplete-line; "a\n": 1 line; "a\nb": 1 line, 1 incomplete-line;
+                       // Gitea uses the definition (like most modern editors):
+                       //   empty: 0 lines; "a": 1 line; "a\n": 2 lines; "a\nb": 2 lines;
+                       //   When rendering, the last empty line is not rendered in UI, while the line-number is still counted, to tell users that the file contains a trailing EOL.
+                       //   To make the UI more consistent, it could use an icon mark to indicate that there is no trailing EOL, and show line-number as the rendered lines.
+                       // This NumLines is only used for the display on the UI: "xxx lines"
                        if len(buf) == 0 {
                                ctx.Data["NumLines"] = 0
                        } else {