Add a doc comment to StringReplace

[GeckoEidechse]

This is an initial test to get formatting etc agreed upon to then build on this further

Related to #664

[GeckoEidechse]

So looking at this in the diff rn, I think we should drop the ///--------- decorators before/after doc comment cause it just adds more (unnecessary lines).

So like

...
string function GetMapDisplayDesc( string mapname )
{
	return "#" + mapname + "_CLASSIC_DESC"
}

/// Sends a string message to player
/// * `baseString` - The input string to search through
/// * `searchString` - Find this substring...
/// * `replaceString` - ...and replace with this substring
/// * `replaceAll` - Whether to replace all occurences or just the first
/// * `caseInsensitive` - Whether to consider casing (upper/lower)
///
/// Returns the updated string
string function StringReplace( string baseString, string searchString, string replaceString, bool replaceAll = false, bool caseInsensitive = false )
{
	bool loopedOnce = false
	string source = caseInsensitive ? baseString.tolower() : baseString
	var findResult = source.find( searchString )
	while ( findResult != null  && !(loopedOnce && !replaceAll))
	{
		string part1 = baseString.slice( 0, findResult )
		string part2 = baseString.slice( findResult + searchString.len(), baseString.len() )

		baseString = part1 + replaceString + part2
...

vs

...
string function GetMapDisplayDesc( string mapname )
{
	return "#" + mapname + "_CLASSIC_DESC"
}

///-----------------------------------------------------------------------------
/// Sends a string message to player
/// * `baseString` - The input string to search through
/// * `searchString` - Find this substring...
/// * `replaceString` - ...and replace with this substring
/// * `replaceAll` - Whether to replace all occurences or just the first
/// * `caseInsensitive` - Whether to consider casing (upper/lower)
///
/// Returns the updated string
///-----------------------------------------------------------------------------
string function StringReplace( string baseString, string searchString, string replaceString, bool replaceAll = false, bool caseInsensitive = false )
{
	bool loopedOnce = false
	string source = caseInsensitive ? baseString.tolower() : baseString
	var findResult = source.find( searchString )
	while ( findResult != null  && !(loopedOnce && !replaceAll))
	{
		string part1 = baseString.slice( 0, findResult )
		string part2 = baseString.slice( findResult + searchString.len(), baseString.len() )

		baseString = part1 + replaceString + part2
...

The Discord vote a while back was also slightly in favour of a format that doesn't have the decorators though our conclusion back when the vote was done was to combine the two most voted versions

[ASpoonPlaysGames]

Ok so, yeah drop the decorators.

But also, do we actually need doc comments for squirrel functions? Squirrel is scripting, mostly not stuff that is reused

[GeckoEidechse]

Ok so, yeah drop the decorators.

Done with c3eba08

But also, do we actually need doc comments for squirrel functions? Squirrel is scripting, mostly not stuff that is reused

The reason is to both improve readability and to then be able to auto-generate documentation directly from code ^^

[F1F7Y]

So looking at this in the diff rn, I think we should drop the ///--------- decorators before/after doc comment cause it just adds more (unnecessary lines).

The entire point of the separators is to add more lines to make it visually easier to separate the comment from code, not all of us have syntax highlighting... I can see how it could get annoying to have to copy paste these and they dont add anything to the docs so whatever the hivemind wants we go with

[GeckoEidechse]

The entire point of the separators is to add more lines to make it visually easier to separate the comment from code, not all of us have syntax highlighting...

Regarding syntax highlighting, we might wanna do a poll on dev setups people use to see what we should target. I'm pretty sure vscode is the highest (and that one has an extension for squirrel). Curious what is second. Probably Notepad++ but not sure if that has any highlighting for Squirrel.

(sidenote: the occasional lack of Syntax highlighting is also why I have a disliking for /* ... */ style comments :P)

I can see how it could get annoying to have to copy paste these and they dont add anything to the docs so whatever the hivemind wants we go with

For me it's mostly the visual clutter they add. I think the easiest solution is to just do a poll on what people prefer and go with that. Imma set one up.
In the end regardless of which one we go for, if we ever wanna change adding/removing the decorators should be quite easy.

[GeckoEidechse]

Made a poll in #759

[GeckoEidechse]

Made a poll in #759

Poll is currently at 7:2 in favour of no decorators so I'd say we do no decorators for now ^^

[ASpoonPlaysGames]

Code looks good (lol its a comment)

Since it's just a comment, testing isn't needed