Re: [Wireshark-dev] Wireshark Developer's Guide feedback

[Jaap Keuter]

Hi,

Thank you. I've created MR 15081 
 to address most 
of these concerns. I leave to update to the text the someone more in tune with 
the Lua API, I'm not sure what the best way to document this polymorphic beast is.


Thanks,
Jaap


On 3/29/24 7:23 PM, Krefta, Oliver O. - US via Wireshark-dev wrote:

Hi,

I've been using the Wireshark Developer's Guide ( 
https://www.wireshark.org/docs/wsdg_html/ 
  ) as a reference for developing a 
dissector using the Lua API. In doing so, I noticed a few potential errors in 
the documentation and wanted to give feedback.


Section 11.6.2.5
My understanding is that tvb:reported_length_remaining() takes an optional 
parameter specifying an offset. My own testing seems to confirm this. However 
the function is documented as taking no parameters.


Section 11.7
This section seems to have some formatting issues. Several of the documented 
API functions are children of the "Example" subsection 11.7.2 when they should 
be contained in the "TreeItem" subsection 11.7.1.
Additionally, the documentation for treeitem:add() and similar functions have 
mismatched brackets in the sentence:


This function has a complicated form: 'treeitem:add([protofield,]
[tvbrange,] value], label)', such that ...

(In fact that whole paragraph is a bit confusing to understand).


Hopefully you find this useful in improving the documentation.

Thanks,
Oliver Krefta
___
Sent via:Wireshark-dev mailing list 
Archives:https://www.wireshark.org/lists/wireshark-dev
Unsubscribe: https://www.wireshark.org/mailman/options/wireshark-dev
 mailto:wireshark-dev-requ...@wireshark.org?subject=unsubscribe

Re: [Wireshark-dev] Wireshark Developer's Guide feedback

[Guy Harris]

On Mar 29, 2024, at 11:23 AM, Krefta, Oliver O. - US via Wireshark-dev 
 wrote:

> Section 11.6.2.5
> My understanding is that tvb:reported_length_remaining() takes an optional 
> parameter specifying an offset. My own testing seems to confirm this. However 
> the function is documented as taking no parameters.

Yes.  That documentation is generated automatically from the Wireshark source 
code that implements the Tvb class, but the C source code for that particular 
function wasn't using the proper convention to cause the documentation 
generator to recognize the argument.  That's been fixed in the main branch and 
in the 4.2, 4.0, and 3.6 branches.

> Section 11.7 
> This section seems to have some formatting issues. Several of the documented 
> API functions are children of the "Example" subsection 11.7.2 when they 
> should be contained in the "TreeItem" subsection 11.7.1.

The "Example" subsection should be subsection 11.7.1.2.1, i.e. it should be a 
subsection of 11.7.1.2.

> Additionally, the documentation for treeitem:add() and similar functions have 
> mismatched brackets in the sentence:
> This function has a complicated form: 'treeitem:add([protofield,] [tvbrange,] 
> value], label)', such that ...
> (In fact that whole paragraph is a bit confusing to understand).

This *function* is a bit confusing to understand.  I'm not sure anything other 
than examples of every single possible way in which it can be called would be 
understandable.
___
Sent via:Wireshark-dev mailing list 
Archives:https://www.wireshark.org/lists/wireshark-dev
Unsubscribe: https://www.wireshark.org/mailman/options/wireshark-dev
 mailto:wireshark-dev-requ...@wireshark.org?subject=unsubscribe