Projectile: Code: Fix \brief for doxygen

[smiths]

The \brief tag in the generated Projectile.py file is currently a comment to the developers, as opposed to a comment to users of the code. The current tag says "Contains the entire Projectile program." We should fix this to provide the purpose of the program. The purpose \brief should be "Efficiently and correctly predict whether a launched projectile hits its target." Ideally the purpose here should come from the same source as for the README file (#3159) and the SRS.

[hrzhuang]

I am trying to use the purpose for the \brief. A problem is that the purpose is used in the introduction of the Problem Description section of the SRS, where it follows "A system is needed to ..." so the verb "predict" needs to be plural. But in the \brief it would be more natural to use the singular form, i.e. "Efficiently and correctly predicts whether a launched projectile hits its target." I think the most "do-the-right-thing" approach here is to attach more grammatical information to purpose so that it can be conjugated differently in different places, but I haven't found any existing infrastructure to facilitate something like this. Alternatively, a quick workaround would be to add "A program to ..." at the beginning of the \brief. Thoughts?

[smiths]

I added a comment in #3248 (#3248 (comment)) that seems relevant here. If we distill the purpose into its essential elements, instead of thinking of it as a line of text in an introduction, then we would drop the "efficiently and correctly" part. The purpose would now just be the "functional purpose". (I used functional in the same sense as functional requirements. The purpose is what the software does, not the quality of how it does it.) If the purpose is simply "predict whether a launched projectile hits its target", we could use that in the README and (I think) in the introduction by changing the sentence to "A program to ..." as you suggest. I feel like that pattern could be repeated across all of the examples.

[hrzhuang]

I see, that makes sense! Should we keep the non-functional requirements in the introduction of the Problem Description section (as we did in #3419)? If so, it seems apt to drop "correctly" nevertheless (as you mentioned in your comment on #3248).

[smiths]

I'm fine with keeping the non-functional requirements in the introduction. We do want the software to be efficient, even though we don't do much about it other than say what we want. 😄