Details

    • Type: Bug
    • Status: Resolved
    • Priority: Minor
    • Resolution: Fixed
    • Affects Version/s: 2.0.0uimaFIT
    • Fix Version/s: 2.1.0uimaFIT
    • Component/s: uimaFIT
    • Labels:
      None

      Description

      The second example in 7.1.1 Regular UIMA components of http://uima.apache.org/d/uimafit-current/tools.uimafit.book.html#ugr.tools.uimafit.introduction reads

      UimaUtil.TOKEN_TYPE_PARAMETER, Token.class.getName(),
      UimaUtil.SENTENCE_TYPE_PARAMETER, Sentence.class.getName

      Shouldn't it be

      Tokenizer.TOKEN_TYPE_PARAMETER, Token.class.getName(),
      Tokenizer.SENTENCE_TYPE_PARAMETER, Sentence.class.getName());());

      ?

        Activity

        Hide
        rec Richard Eckart de Castilho added a comment -

        Good point, Marshall Schor.

        Reopening as a reminder to add an explanatory note to the documentation.

        Show
        rec Richard Eckart de Castilho added a comment - Good point, Marshall Schor . Reopening as a reminder to add an explanatory note to the documentation.
        Hide
        schor Marshall Schor added a comment -

        There's another trade-off / fine-line-to-walk possible here, informed by the principle of least surprise . So, when you document some example, which (to new readers) seems confusing, because it's "required" by the particular things in your example, you could choose to acknowledge the potential surprise by adding a short comment - something like "you might be surprised that these constants are in the UimaUtil class/interface, rather than the Tokenizer class/interface, but that's where those components define them!

        The downside of adding things like this is that your documentation gets longer. And today's reader of documentation is probably impatient, and somewhat annoyed by longer docs.

        There's things you can do with formatting to mitigate this kind of thing, like making it a "note", perhaps in slightly smaller font, so it's subordinate to the main "flow", visually.

        Show
        schor Marshall Schor added a comment - There's another trade-off / fine-line-to-walk possible here, informed by the principle of least surprise . So, when you document some example, which (to new readers) seems confusing, because it's "required" by the particular things in your example, you could choose to acknowledge the potential surprise by adding a short comment - something like "you might be surprised that these constants are in the UimaUtil class/interface, rather than the Tokenizer class/interface, but that's where those components define them! The downside of adding things like this is that your documentation gets longer. And today's reader of documentation is probably impatient, and somewhat annoyed by longer docs. There's things you can do with formatting to mitigate this kind of thing, like making it a "note", perhaps in slightly smaller font, so it's subordinate to the main "flow", visually.
        Hide
        rec Richard Eckart de Castilho added a comment -

        I'm afraid, it is the way that the OpenNLP UIMA components are implemented. I'll mark this bug here as invalid.

        Show
        rec Richard Eckart de Castilho added a comment - I'm afraid, it is the way that the OpenNLP UIMA components are implemented. I'll mark this bug here as invalid.
        Hide
        ithohd9u Armin Wegner added a comment -

        No, I haven't tested it. It just looks unreasonable to have parameters prefixed UimaUtil for an AE named Tokenizer. It's confusing in an introduction. It also looks like one of those copy-and-paste errors I sometimes make.

        Show
        ithohd9u Armin Wegner added a comment - No, I haven't tested it. It just looks unreasonable to have parameters prefixed UimaUtil for an AE named Tokenizer. It's confusing in an introduction. It also looks like one of those copy-and-paste errors I sometimes make.
        Hide
        rec Richard Eckart de Castilho added a comment -

        Questions should go to the users mailing list, but I'll assume that you say this is a bug.

        Did you actually try "Tokenizer.TOKEN_TYPE_PARAMETER"? Neither opennlp.uima.tokenize.AbstractTokenizer nor opennlp.uima.tokenize.Tokenizer declare such a constant. They refer to the constants defined in UimaUtil. If you try it, you should notice that you get a compiler error.

        Show
        rec Richard Eckart de Castilho added a comment - Questions should go to the users mailing list, but I'll assume that you say this is a bug. Did you actually try "Tokenizer.TOKEN_TYPE_PARAMETER"? Neither opennlp.uima.tokenize.AbstractTokenizer nor opennlp.uima.tokenize.Tokenizer declare such a constant. They refer to the constants defined in UimaUtil. If you try it, you should notice that you get a compiler error.

          People

          • Assignee:
            rec Richard Eckart de Castilho
            Reporter:
            ithohd9u Armin Wegner
          • Votes:
            0 Vote for this issue
            Watchers:
            3 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development