uima-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Marshall Schor (JIRA)" <...@uima.apache.org>
Subject [jira] [Commented] (UIMA-3250) Wrong qualifier
Date Thu, 05 Sep 2013 13:50:53 GMT

    [ https://issues.apache.org/jira/browse/UIMA-3250?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13759074#comment-13759074
] 

Marshall Schor commented on UIMA-3250:
--------------------------------------

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.
                
> Wrong qualifier
> ---------------
>
>                 Key: UIMA-3250
>                 URL: https://issues.apache.org/jira/browse/UIMA-3250
>             Project: UIMA
>          Issue Type: Bug
>          Components: uimaFIT
>    Affects Versions: 2.0.0uimaFIT
>            Reporter: Armin Wegner
>            Assignee: Richard Eckart de Castilho
>            Priority: Minor
>
> 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());());
> ?

--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira

Mime
View raw message