Root / Assembly / ARCCore / AREnumType / DocumentationOnlyEnum / ARConcepts / _Member / LinkInsertionInDocumentation



DescriptionDocumentation with links is much easier to read.

On the other hand, inserting links can often be quite tedious in a typical markup language.

AgoRapide 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.

If 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).

If this is done methodically, then any mechanism for creating for instance HTML documentation, (like the one offered in ARCDoc, that was by the way just an example of linking) can then first identify all terms (or files) that are created, and then blindly replace in the text -[Filename]- with '<a href="[Filename]">[Filename]</a>' without actually knowing anything about the text's structure.

This is a pragmatic approach that works surprisingly well.
See also doc.
LongDescriptionFAQ: Why does AgoRapide not use XML comments (comments beginning with three slashes, '///')?
AgoRapide in general does not use XML comments.
That 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.
They 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).
(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).

4 items

Generated 2020-10-13 11:11:01.131 UTC