[jira] Commented: (HARMONY-3077) add the Encoder Library description to the site

["Nadya Morozova (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/HARMONY-3077?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12468341 ] 

Nadya Morozova commented on HARMONY-3077:
-----------------------------------------

Hi Sveta!
Seems like a new doc is born, great news! thanks. A couple of generic comments below:
- I guess you don't need to add Back To Top links manually - these should be added automatically by Anakia during parsing, right?
- site.css: i expect the doc will be posted in the drlvm folder of the site, where there's a copy of site.css, no need to go to the root folder in the link
- generic grammar: i don't always follow your choice of usage vs. absence of the definite article; could you please double-check the doc for article usage consistency?
- Intel64 - do we really only support Intel64? what about amd64? 
- section 2 (overview) consider adding a link to the DRLVM index page
- section 2: are .opt and .jet two components? there's one doc about the two of them; do you think it's reasonable to merge the two bullets into one since they reference the same doc?
- section 3: bullet 1 uses "which is" and bullet 2 "that is"; suggest that we make them parallel constructions for easier reading
- section 3: "To satisfy clients special needs" > "To satisfy clients' ..."
- section 3: "To satisfy clients special needs, use adapters, which provide ..." I don't understand. Am I to try and satisfy clients? Or does the library try to satisfy clients by providing handy adapters? "use adapters" reads as an imperative and I am all confused ;( 
- section 4: "About 150 instructions: arguments quantity" - do you mean "About 150 instructions, which cover the following areas: arguments quantity" or something similar?
- section 4: "arguments roles, that is whether..." and "additional miscellaneous information, for example whether" comma missing before "whether"
- section 4: "The most popular instructions are in place already" - you mean not all of these 150 functions are implemented? if so, please make this key statement more apparent; otherwise, it seems the whole 150 are in place and ready for use.
- section 4: missing definition of "A decoding (disassembling) engine"
- section 4: "The encoder library contains the following files located at" > consists of? relies on? Contains and Is located at are very close in meaning, so the current version sounds a bit weird
- section 5: "common generic interface" isn't this tautology?
- section 5.1: does the section mention all the adapters currently available? if so, please make them a list and not examples + some text. this way, a reader will have the chance to easily find the adapter they need to read about most of all.
- section 5.2.2: dynamic and static data terms are highlighted the second (and not the first time they are used)
- section 5.2.2: i don't quite understand why it's necessary to explain how the encode *does not* work ("This algorithm helps to avoid the following loop on the hot execution path, as shown below:"); perhaps, we could abridge the section to only show how the encoder works (not to confuse readers)
- third-party disclaimer: do you need this? 


> add the Encoder Library description to the site
> -----------------------------------------------
>
>                 Key: HARMONY-3077
>                 URL: https://issues.apache.org/jira/browse/HARMONY-3077
>             Project: Harmony
>          Issue Type: Task
>          Components: Website/Documentation
>            Reporter: Svetlana Konovalova
>         Assigned To: Nadya Morozova
>         Attachments: encoder_library.html, encoder_library.xml
>
>
> add the Encoder Library document to the site [to the subcomponents/drlvm directory ]

-- 
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.