/ doc / toc / ARCCore / Enum / ARConcepts / LinkInsertionInDocumentation / __TOCDet / Attribute

Attribute

Edit keys at this level only

Description = Documentation with links is much easier to read.0x000D0x000A0x000D0x000AOn the other hand, inserting links can often be quite tedious in a typical markup language.0x000D0x000A0x000D0x000AAgoRapide offers a very easy method for link insertion: You just prepend and append the relevant word that you want a link to, with a minus sign / hyphen, '-' in the documentation.0x000D0x000A0x000D0x000AIf the relevant word is a C# identifier, you should in addition use the 'nameof' keyword, in order to catch renames and deletions of terms and also in order to be able to easy navigate within your developing environment (like when working within Visual Studio, using F12).0x000D0x000A0x000D0x000AIf this is done methodically, then any mechanism for creating for instance HTML documentation, (like the one offered in -ARCDoc-),  can then first identify all terms (or files) that are created, and then blindly replace in the text -0x005BFilename0x005D- with '0x003Ca href="0x005BFilename0x005D"0x003E0x005BFilename0x005D0x003C/a0x003E' without actually knowing anything about the text's structure.0x000D0x000A0x000D0x000AThis is a pragmatic approach that works surprisingly well.0x000D0x000ASee also -doc-.0x000D0x000A0x000D0x000ASome classes in -ARCDoc- that support link insertion are -HLocation-, -HLocationCollection-, -DocLink- and -DocLinkCollection- and also -DocLinkResolution- (which resolves ambigious links).0x000D0x000A
EnumMember = LinkInsertionInDocumentation
EnumType = ARConcepts
LongDescription = FAQ: Why does AgoRapide not use XML comments (comments beginning with three slashes, '///')?0x000D0x000AAgoRapide in general does not use XML comments.0x000D0x000AThat is because XML comments are not included in the C# language, nor are they included in the compiled executable, that is, they are not available at run-time within the application.0x000D0x000AThey are also weakly referenced, meaning that if Intellisense or similar do not catch a rename or a deletion of some term, then the references to it will become a dead link (in other words, XML comments are prone to link-rot).0x000D0x000A(There is of course some use of XML comments in AgoRapide, especially when it is directly applicable to helping you as a developer to understand how to use a specific method or a specific parameter to a method).

Edit keys at all sub levels.
NOTE: Edits are always additive. Use 'Invalid' in order to delete keys.

Edit single sub keys only: Description / EnumMember / EnumType / LongDescription

Generated 2025-05-23 08:07:43.442 UTC