Internal Source Code Documentation - FiM++ [closed]

Question

Closed. This question needs to be more focused. It is not currently accepting answers.

---

Want to improve this question? Update the question so it focuses on one problem only by editing this post.

Closed 3 years ago.

Improve this question

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

Answer 1

Sorry no one's given this any concern before me! I'm heading development of the language, so I think I have a good grasp on the answer, here.

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

I've never considered an auto documentation technique like Javadoc, so there is no formal syntax for that. The compiler I'm working on completely discards comments, so it won't support it, but I'm sure it wouldn't be terribly hard.

1. 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 pony-written letter is one of the core design paradigms).

The idea of the author name on the last line was intended for the foremost author of the report, so multiple authors was never suggested before now. However, Your faithful students, would work nicely!

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

Indeed! Perhaps something at the bottom of the report, like

(Written 2013-04-11)

Hope this help you. You have some great ideas, here, too! You should join the team!