RFR: 8290775: Some doc errors in DerOutputStream.java [v5]

[jquanC]

On Sat, 23 Jul 2022 05:29:07 GMT, jquanC <duke at openjdk.org> wrote:

>> There are some doc errors in sun.security.util.DerOutputStream, like the followings,
>> 
>> 
>> /**
>>  * Private helper routine for writing DER encoded string values.
>>  * @param s the string to write
>>  * @param stringTag one of the DER string tags that indicate which
>>  * encoding should be used to write the string out.
>>  * @param enc the name of the encoder that should be used corresponding
>>  * to the above tag.
>>  */
>> private void writeString(String s, byte stringTag, Charset charset) throws IOException
>> 
>> The parameter is charset, but not enc.
>> 
>> 
>> /**
>>  * Marshals a DER integer on the output stream.
>>  *
>>  * @param i the integer in bytes, equivalent to BigInteger::toByteArray.
>>  */
>> public void putInteger(byte[] buf) throws IOException {
>> 
>> The parameter is buf, but not i.
>
> jquanC has updated the pull request incrementally with one additional commit since the last revision:
> 
>   8290775: Some doc errors in DerOutputStream.java  Update: add a modification and improve an expression according to the specification

Thanks for your valuable advice. I will continue to improve.
Best wishes!




------------------ 原始邮件 ------------------
发件人:                                                                                                                        "openjdk/jdk"                                                                                    ***@***.***>;
发送时间: 2022年7月22日(星期五) 中午1:25
***@***.***>;
***@***.******@***.***>;
主题: Re: [openjdk/jdk] 8290775: Some doc errors in DerOutputStream.java (PR #9585)





  
On the second point, I have some doubts. 1) Here don't need to add @.*** charset" because it's clear to everyone? @.*** enc" does not seem to be used in the method. Shouldn't it be deleted?
  
Sorry for the confusing.
 
I think it is fine to update the "param enc" to "param charset", but it may be not necessary to update the parameter description.  With "parameter description", I refer to this part, "the name of the encoder that should be used corresponding to the above tag".
 
The parameter description may be still confusing to someone, as the 'the name of the encoder' is not well-defined here.  Maybe, it could be simplified as "the charset that ..."
 
Here is the proposed update:
  
 * @param enc the name of the encoder that should be used corresponding  
 
  
to the above tag.
  
   
  
@param charset the specified character set encodes a string into a
  
 
  
sequence of bytes using
  
  
I may use an update like :
  
 * @param enc the name of the encoder that should be used corresponding  
 
  
to the above tag.
  
   
  
@param charset the charset that is should used corresponding to the
  
 
  
above tag.
  
  
—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you were mentioned.Message ID: ***@***.***>

-------------

PR: https://git.openjdk.org/jdk/pull/9585