Method Documentation

[eduard93]

• Use documatic formatting (basically HTML)
• All that can be in a signature must be in a signature, eg. ClassMethod Read(FileName As %String, Length As %Integer(MINLEN=1) = 32656, ByRef Status As %Status) As %String
• Do not duplicate in documentation what is in a signature
  • Length is a positive integer
  • Default length is 32656
  • etc - it's all obvious from a signature
• Documentation is for everything else: This methods returns first Length characters from FileName, check Status for errors
• Signature must correspond to what's inside the method
• Ideally, signatures are consistent across project
  • Return status (but not, for example some methods return status, some - exception)
  • etc
• Provide defaults for unrequited parameters
• Do not provide defaults for main (id/oref etc) parameters

[eduard93]

Do not add ByRef where it's not required.