DWF documentation issues

[Guest]

Hi,

 

I am updating pydwf with the latest beta release (3.20.31). As part of that process, I am re-reading the documentation (dwfsdk.pdf), to merge the accumulated changes into the pydwf documentation. For now, this mostly concerns updating the enums. Concerning those, I have the following questions.

Section 2 , the DWFERC enumeration:

The descriptions of values 1 and 2 are identical, which is not very useful - it may be a mistake. Could this be fixed?

Enum ACQMODE is defined inconsistently between section 5.2 and section 9.2, and ythe header file.

This is what section 5.2 says:

This is what section 9.2 says:



There's conflicted definitions for the values 5 and 6.

The dwf.h header file says this:



Which is, again, different.

I suppose this should be corrected.


Question: as mentioned before, I think the dwfsdk.pdf documentation has a lot of room for improvement. If useful, I could point out particular unclarities/omissions. Let me know if that is useful, or if the priority of improving the documentation is just too low for that.

Cheers Sidney

 

[Guest]

Has this been read by anyone, Digilent-side?

[Guest]

Hi @attila

Could I get a response to my remarks about the documentation?

 

I am wondering most of all which one of the three sources on ACQMODE values is the correct one.

[attila]

Hi @reddish

Thank you for the observation.

The header file always contains the correct definition.

As usual, I corrected and replied immediately, but for some reason it seems that the message was not sent.

[Guest]

Hi @attila

Can you please also address the issue about the duplicate description in DWERC?

Can you please also address the question about whether or not it will be useful for me to point out which sections of the documentation are simply unclear to outsiders without intimate knowledge of the source code? As indicated earlier, I feel that dwfsdk.pdf is currently at the level of company-internal documentation, which means it is hard or impossible to understand some parts for outsiders like me. There's just a lot of context that's missing. For some of the finer points of DWF functionality, I've had to resort to experimentation to figure out what functions or enumeration options really do; and for some functions and enumeration options, I wouldn't know where to start.

I hope you agree that's not how it should be.

[attila]

Hi @reddish

Yes, it is corrected.

Feel free to ask if something is unclear.

[Guest]

Hi @attila

> Feel free to ask if something is unclear.

I'll take that as a "documentation quality is not a priority". Which sucks a bit.