[COFF] Clarify comment. NFC

[smeenai]

Summary

Reid pointed out the string table for supporting long section names is a
BFD extension and the comments should reflect that. Explicitly spell out
link.exe's and binutil's behavior around section names and the rationale
for LLD's behavior.

[mstorsjo]

COFF/Writer.cpp

577 ↗

(On Diff #131867)

Not sure about non-standard though, since iirc dumpbin at least shows them correctly - so the extension is at least acknowledged by MS that much.

[smeenai]

Super belated ping.

COFF/Writer.cpp

577 ↗

(On Diff #131867)

It's non-standard in the sense that the spec explicitly says "Executable images do not use a string table and do not support section names longer than 8 characters." My guess is that dumpbin either doesn't specialize the string table reading logic for executables (i.e. it just uses the same logic for object files and executables), or they explicitly allow it to play better with binutils. Either way, I think non-standard is a fair way to put it.

[rnk]

lgtm, this is very clear. :)

[ruiu]

LGTM

lld/trunk/COFF/Writer.cpp

default: {
     Sym.SectionNumber = Sec->SectionIndex;
     break;
   }
   }
   return Sym;
 }
 
 void Writer::createSymbolAndStringTable() {
-  // Name field in the section table is 8 byte long. Longer names need
-  // to be written to the string table. First, construct string table.
+  // PE/COFF images are limited to 8 byte section names. Longer names can be
+  // supported by writing a non-standard string table, but this string table is
+  // not mapped at runtime and the long names will therefore be inaccessible.
+  // link.exe always truncates section names to 8 bytes, whereas binutils always
+  // preserves long section names via the string table. LLD adopts a hybrid
+  // solution where discardable sections have long names preserved and
+  // non-discardable sections have their names truncated, to ensure that any
+  // section which is mapped at runtime also has its name mapped at runtime.
   for (OutputSection *Sec : OutputSections) {
     if (Sec->Name.size() <= COFF::NameSize)
       continue;
-    // If a section isn't discardable (i.e. will be mapped at runtime),
-    // prefer a truncated section name over a long section name in
-    // the string table that is unavailable at runtime. Note that link.exe
-    // always truncates, even for discardable sections.
     if ((Sec->getPermissions() & IMAGE_SCN_MEM_DISCARDABLE) == 0)
       continue;
     Sec->setStringTableOff(addEntryToStringTable(Sec->Name));
   }
 
   if (Config->DebugDwarf) {
     for (ObjFile *File : ObjFile::Instances) {
       for (Symbol *B : File->getSymbols()) {