Style preference for doc comments in Squirrel

[GeckoEidechse]

Background

In order to achieve the goal of autogenerating documentation for Squirrel code we need some way to indicate doc comments.

The rough style was already chosen in a past poll on Discord, including using triple slash (///) to differentiate doc comments from standard code comments (//) as well as the rough format for arguments and return values.

What remains is to decide whether to include decorators (///------) in the doc comments or not.

 

Poll

What speaks in favour of decorators:

• Makes doc comments more recognisable when no syntax highlighting is available

What speaks against decorators:

• Adds unnecessary clutter to source code

 

Examples

Decorators

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

No decorators:

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

---

If you have any further arguments in favour or against decorators, please LMK and I'll add them to the poll

[laundmo]

just noting here that if you want these to show on ModdingDocs you'll have to translate them to .rst syntax

[GeckoEidechse]

Yup. Actual translation for ModdingDocs etc is a whole separate issue. RST syntax is kinda ugly to write so approach would probably be some custom translation tool.

[laundmo]

it may not be the nicest, but it would allow using features from sphinx extensions like a inline youtube player or everything from https://sphinx-design.readthedocs.io/en/latest/

[Zanieon]

I'm inclined to say that having not only decorators, but also ASCII Art because yes.

But if others don't want, then fine i guess, no decoratiors is already what we work with.