Document the line-number counting behavior (#27386)

Ref #27377

1 files changed, 7 insertions, 2 deletions

diff --git a/routers/web/repo/view.go b/routers/web/repo/view.go
index 9085bda395..6571790627 100644
--- 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 {