harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Svetlana Konovalova (JIRA)" <j...@apache.org>
Subject [jira] Commented: (HARMONY-3077) add the Encoder Library description to the site
Date Tue, 30 Jan 2007 13:19:33 GMT

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

Svetlana Konovalova commented on HARMONY-3077:
----------------------------------------------

Nadya, thank you so much for the detailed review! 
Alex, thanks for your help as well!
Taking into consideration all the comments, the new file is created!  

[NM]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?
[SK]We do not add these links to the xml files, because they are inserted automatically during
parsing. But when we deal with the html docinclude, Anakai doesn't add the necessary links.((
please right me, if I'm wrong. 

[NM]- 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
[SK]Right, thanks. Fixed.

[NM]- 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?
[SK] Checked.

[NM]- Intel64 - do we really only support Intel64? what about amd64? 
[AA] They are binary compatible, so the Intel64 also implies amd64.
[Sk] was decided to leave as it is, right?

[NM]- section 2 (overview) consider adding a link to the DRLVM index page
[SK]Great idea!

[NM]- 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?
[SK]Well, there is sense in what you are saying, no doubt. But my idea was to enumerate components,
but not docs. AFAIU, .opt and .jet are two DRLVM components described in one doc. What do
you think?
 
[NM]- section 3: bullet 1 uses "which is" and bullet 2 "that is"; suggest that we make them
parallel constructions for easier reading
[SK]Once they were parallel, but you suggested changing the first sentence :))) well, I'll
use "which", ok?

[NM]- section 3: "To satisfy clients special needs"  "To satisfy clients' ..."
[SK]Thanks. Changed.

[NM]- 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 ;( 
[SK]Sorry, my fault. I paraphrased the sentence. "Clients with    
special needs should use adapters, which provide handy and 
convenient interface and then translate the data into generic interface."
hope it sounds better now. 

[NM]- section 4: "About 150 instructions: arguments quantity" - do you mean "About 150 instructions,
which cover the following areas: arguments quantity" or something similar?
[SK]You are right! Fixed.

[NM]- section 4: "arguments roles, that is whether..." and "additional miscellaneous information,
for example whether" comma missing before "whether"
[SK]Thanks.

[NM]- 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.
[AA]Yes, 150+ instructions are ready. 
The modern IA-32 and Intel64 instruction set contains much more instructions. 
We start filling from the most popular ones, and now we have these 150.
[SK]Paraphrased.

[NM]- section 4: missing definition of "A decoding (disassembling) engine"
[SK] added

[NM]- 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
[SK] agree. "Consists of" in fine

[NM]- section 5: "common generic interface" isn't this tautology?
[AA] Hmmm.. I was thinking about something like "common" as "the same for everyone" as it
exposes a single method. And about "generic" as "wide enough to cover most of its need into
a single function".
[SK]Makes sense...
I found out this very phrase in IBM docs... [http://www.cadence.ru/company/cadence_labs/kuehl_IBM_1994_Verity.pdf]


[NM]- 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.
[AA]Yes. Currently, we have 3 of them. Two of them are very special, and strictly targeted
to their clients (these are adapter in Jitrino.JET and adapter in Jitrino.OPT).
The latter one is what most of programmers need, and its declarations are in encoder.h.
This adapter is often informally referred ad 'encoder', for example 'a stub >was written
using encoder'. :-)
[SK]I've made a list of adapters, removed the note, since its info is in the list now. Please
check.


[NM]- section 5.2.2: dynamic and static data terms are highlighted the second (and not the
first time they are used)
[SK]Fixed.

[NM]- 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)
[AA] In fact, this IS how it works. :-)
The "hot execution path" normally refers to a program section that spends a >lot of time.
This is the subject for various optimizations. Some of them may contain
- reducing number of instructions in the path
- reducing number of memory accesses
- (sic!)removing loops from the hot path 
- and there are more...
Often, the loops are the root of the evil, that's why this section exactly states why 
we do such things - we optimize (and speed up) execution by *removing* the loop.
[SK]Paraphrased.

[NM]- third-party disclaimer: do you need this? 
[SK]No. removed.


Thanks a lot!
Sveta


> 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.


Mime
View raw message