Commenting "unsupported" functions/options/etc.

[Cheetham, Anastasia]

We recently discussed (in dev meetings and on-list) the fact that we have some things in our public namespace that we do not want or expect our users to actually use. We decided we would tag these as "unsupported" and leave them undocumented.

Justin has added a JIRA to the bug parade for the task of adding comments to the code for this:
   http://issues.fluidproject.org/browse/FLUID-3881

For this release, this JIRA will be part of the general code-cleanup process, but in the future, we need to include this task as part of our daily coding practices. If you're creating something that's accessible to the user, be it
  a) public free functions i.e. functions in the public namespace, such as fluid.inlineEdit.foo() 
  b) methods and instance variables on an object returned by any creator function 
  c) options defined in a defaults block or otherwise processed in the code but not for public use 
  d) return values

please think about whether or not it is something you want or expect users to use. If so, add helpful comments to functions, etc. If not, add a commented that it's "unsupported" with a note explaining why. It will be a lot easier to think about these things while we're writing the code, rather than having to go back later and remember what we were thinking at the time.

Having these comments in the code will greatly simplify the process of updating the documentation, as well.

-- 
Anastasia Cheetham     Inclusive Design Research Centre
acheetham at ocad.ca            Inclusive Design Institute
                                        OCAD University