Feature request: Include .strings file comment in generated type documentation

[nolanw]

For example, if I have in my .strings file:

"search-placeholder" = "Search %@"; /* Parameter is name of category. */

it'd be awesome to have the generated function and property documentation do something like

/// Base translation: Search %@
/// 
/// Locales: Base
///
/// - Note: Parameter is name of category.

so you get the localizer note right at the code use site. It's a helpful reminder of what the string is meant for and what the parameters are. It also makes bad/outdated localizer notes a bit more visible so maybe they can be fixed.

I believe genstrings puts the comment as I've done in my example .strings file, so that's probably as close as we'll get to a standard for comment placement.

Loving R.swift btw, thanks for making it!

[mac-cain13]

@tomlokhorst Do you know if this is easy to do? Are the comments available to us when we parse the file?

Sounds like a nice feature!

[tomlokhorst]

Comments were part of the original design. But they fell off, because the default parsing of a plist file to a NSDictionary doesn't expose them.

I still like the feature, though!

To parse the comments we'd need to create a plist parser that exposes them. Or find a third-party parser that works, I haven't looked for one.

On 26 Jun 2016, at 16:57, Mathijs Kadijk [email protected] wrote:

@tomlokhorst Do you know if this is easy to do? Are the comments available to us when we parse the file?

Sounds like a nice feature!

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

[nolanw]

I had no idea you could parse .strings as a plist using NSDictionary! I can't decide if that's really cool or slightly horrifying ;) But now that you mention it, if you tack curly braces around a .strings file you get an ASCII plist.

I'd assumed there was a lil parser for this already in R.swift. Using NSDictionary makes this a larger feature request than I thought it would be. Sorry about that.

Some random notes for anyone who takes this on (maybe me), or maybe for evaluating an existing parser to bring in:

• The parser needs to consider escapes (e.g. \" doesn't mark the end of the key/value), which I've seen done badly by lots of code that ostensibly parses .strings files.
• There's also \Uxxxx escapes to maybe consider. Surrogate pairs are accepted here by NSDictionary so watch out for those. Experimentally, \U accepts between one and four hex characters.
• I may be wrong about where to put the comment; the Resource Programming Guide says the convention is to put the comment on the line before the string it's describing.

(edited to clarify \U digit count)

[nolanw]

More notes to myself/whoever:

/*
/*
*/
"nested comments?" = "nope";

NSBundle.mainBundle().localizedStringForKey("nested comments?", value: nil, table: nil)

returns nope

[tomlokhorst]

To add to the list of possibilities:

• No quotes are needed, in some cases: key = Value;
• Duplicate keys are ignored (example)
• Multiline keys and values are allowed (example)