1 Topic by Scotty2541 (edited by Scotty2541 2021-06-04 05:07:59)

  • From: Texas
  • Registered: 2020-08-17
  • Posts: 63

Topic: Bad Doc

Hello,
Not a question... a complaint.

It has always been my conclusion that anyone who uses "Doxygen" is demonstrating how lacks their work effort it... The output from it is virtually useless.  Developers spend more time in headers formatting, commenting, etc...  then just writing good doc.  Because it spits out header comments as it's source.

Bereft of examples, lacking cross references, one has to know exactly what one is looking for in order to find it.  A serious "cart before the horse" situation.

But developers slap some comments in the headers, let it spit out useless HTML, and they think the job is done.
Then it remains untouched, out of date from enhancements, broken information when something is changed... Because it's forgotten.

If a real document was part of the package, then a real task of updating it would exist.
(The only "real" doc I can find on this product is a PDF from version 3)

From here:
https://www.wolfssl.com/doxygen/group__ … eca15af4c5

" Certificate file type found in asn_public.h enum CertType. "

Go ahead... click it.  It takes you here
https://www.wolfssl.com/doxygen/asn__public_8h.html

There isn't any "CertType" defined anywhere on that page.
Try typing CertType into the search box...  Nothing.

Now start aimlessly wandering through it's useless menu system hoping to stumble on what you are looking for.

Don't think this is just the first incident where I can't find something, and now left wandering aimlessly.  Nor the second time.  Nor the tenth time...  It gets old really fast.

Broken documentation.  Created by an inferior system.

-Scott
<Code shown is not to scale>

Share

  • Registered: 2015-10-07
  • Posts: 430

Re: Bad Doc

Hi Scott,

Thanks for your feedback on Doxygen quality and will bring up with the team. We strive to keep things well documented, provide timely support and quality examples.

David Garske, wolfSSL

Share

3 Reply by Scotty2541 (edited by Scotty2541 2021-06-04 11:05:18)

  • From: Texas
  • Registered: 2020-08-17
  • Posts: 63

Re: Bad Doc

Thanks.
As I look for answers, troubleshooting issues, examples, etc...  I can show lots of issues.

I could constantly post things, but I don't want to just come across as antagonistic.

I've also though the best example was the MSDN (from about 15 years ago).  No one seems willing to put effort into following that model anymore.

Not just in WolfSSL...  literally everywhere I see these shortcut tools used, the content is horrid.

-Scott
<Code shown is not to scale>

Share

  • From: Texas
  • Registered: 2020-08-17
  • Posts: 63

Re: Bad Doc

dgarske wrote:

Hi Scott,

Thanks for your feedback on Doxygen quality and will bring up with the team. We strive to keep things well documented, provide timely support and quality examples.

David Garske, wolfSSL

David,
I am trying to figure out how to set an alternate name in a certificate...

The doc for "wc_SetAltNames"...
https://www.wolfssl.com/doxygen/group__ … e4fe7e3626
gives this example...

// initialize myCert
if(wc_SetSubject(&myCert, ”./path/to/ca-cert.pem”) != 0) {
    // error setting alt names
}

Subject is NOT Alternate name

-Scott
<Code shown is not to scale>

Share