Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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 but not the 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.

  1. What is the requirement of such internal comment-based documentation? Is there anything in this particular type of syntax that would cause problems?

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

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

share|improve this question

1 Answer 1

up vote 2 down vote accepted

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

share|improve this answer
    
Recommendations to changing the language are open for discussion, as the language is new and in the refining process, as I understand. Thus, if you can make something work by changing it, it may be reasonable. Feel free to expand upon this if it helps further your point. –  Southpaw Hare Jan 18 '13 at 17:13

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.