Uploaded image for project: 'Picard'
  1. Picard
  2. PICARD-1875

Improve function documentation for $firstalphachar

    XMLWordPrintable

    Details

    • Type: Improvement
    • Status: Closed
    • Priority: Normal
    • Resolution: Fixed
    • Affects Version/s: 2.4.0b2
    • Fix Version/s: 2.4
    • Component/s: Documentation
    • Labels:
      None

      Description

      There are functions, like $firstalphachar, that allow the user to set a custom answer to return in case there is no proper answer (in this case, when the first character in the string is not a letter). In Picard’s embedded docs, the function is explained like this:

      `$firstalphachar(text,nonalpha="#")`

      Returns the first character of `text`.

      If `text` is not an alphabetic character `nonalpha` (or `#` if not passed) is returned instead.

      I find this very confusing (but then I’m not a programmer). If I want the custom no answer to be ¡, should I write it as $firstalphachar(text,nonalpha="¡"?

      Bob Swifts documentation explains it like this:

      Usage: $firstalphachar(text[,nonalpha])

      […]

      If `text` does not begin with an alphabetic character, then `nonalpha` is returned instead. If `nonalpha` is not specified, the default value “#” will be used.

      It is much clearer, especially with the examples he gives, but if I read those instructions, I would simply write my function as “$firstalphachar(text,¡)”.

      Are both documentations contradicting each other? Should one be improved? Bob’s explanation makes more sense to me.

        Attachments

          Activity

            People

            • Assignee:
              outsidecontext Philipp Wolfer
              Reporter:
              mfmeulenbelt Maurits Meulenbelt
            • Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

              Dates

              • Created:
                Updated:

                Packages

                Version Package
                2.4