This is a question I originally asked on Stack Overflow, but as a conceptual design question as opposed to a technical issue, I believe it may be more appropriate, or possibly have alternate parallel value, on this board.
The structure of a FiM++ program requires that it end with the closing of a letter and the code author’s name in a specific manner.
Dear Princess Celestia and Stack Exchange and String: A Sample:
...
Your faithful student, Southpaw Hare!
According to the language specification, the keyword “Your faithful student,” (including the comma and following space) is used as an end tag for class definitions, and the following name is a comment with no syntactical effect.
The fact that the author is automatically included (if not strictly required) in every file makes me wonder if it can be used as a form of interpretable documentation akin to Java Docs. In other words, that other programs or editors would be able to parse out this name and use it in some manner.
-
What is the requirement of such internal comment-based documentation? Is there anything in this particular type of syntax that would cause problems?
-
Is the keyword sufficient to fit with the theme? It occurs to me that the lack of ability to use “Your faithful students,” for a plural form (or possibly “Yours faithful,” or “Yours truly,” for an ambiguous version) would make listing multiple authors look awkward and unnatural (and looking like a natural human-written letter is one of the core design paradigms).
-
If creating a Java Docs methodology was considered, then what other features should be included? For one, a date seems common. Including some form of date comment at the top of the letter would probably look natural and not defy the design paradigm.
Since the language is new, unfamiliar to most, and honestly quite silly, here are a few resources to consider:
Original Release Announcement
October Followup
Wiki
What is the requirement of such internal comment-based documentation? Is there anything in this particular type of syntax that would cause problems?
The basic requirement is that the documentation parser knows what that piece of program-text means. This is independent of what a compiler would do with it.
In this case, it helps that the grammar specifies it as a student name.
Is the keyword sufficient to fit with the theme? It occurs to me that the lack of ability to use “Your faithful students,” for a plural form (or possibly “Yours faithful,” or “Yours truly,” for an ambiguous version) would make listing multiple authors look awkward and unnatural (and looking like a natural human-written letter is one of the core design paradigms).
If the documentation must be able to distinguish between one author and multiple authors, then the current keyword alone is not sufficient. The documentation parser would have to infer the presence of multiple authors in a different way (for example by the use of commas or the word ‘and’).
1