NetTalk Central

Author Topic: Service Method - avoid Documentation on some methods  (Read 278 times)

Wolfgang Orth

  • Sr. Member
  • ****
  • Posts: 251
    • View Profile
    • oData Wolfgang Orth
Service Method - avoid Documentation on some methods
« on: June 07, 2022, 06:09:48 AM »
Hello Bruce and all others,

one of my servers has several methods for internal use, some few others for public use.

My intention now is to not doisplay any documentation, parameters, whatever, of those for internal use.

I vaguely recall or at least believe to do, that there has been an option to display such NetWebServiceMethods. Or not. However, I can't find anything alike in NT 11.48. Has this option been in prior versions or did I did my memory fooled me once again?

For the moment I helped myself by putting an OMIT() at the top of each GenerateWSDL, GenerateDocumention and GenerateHelp. Those methods are still listed in the dropdows / list of buttons to pick any documention, pointing to /Methods?ThisSecretThat and so on. Those pages are empty now, but even for me this looks amateurish.

Did I overlook this checkmark?

Or maybe it could become a conditional option?

Any opinion on that?

thanks for reading
Wolfgang

Jane

  • Sr. Member
  • ****
  • Posts: 255
  • Expert on nothing with opinions on everything.
    • View Profile
    • Email

Bruce

  • Global Moderator
  • Hero Member
  • *****
  • Posts: 10758
    • View Profile

Wolfgang Orth

  • Sr. Member
  • ****
  • Posts: 251
    • View Profile
    • oData Wolfgang Orth
Re: Service Method - avoid Documentation on some methods
« Reply #3 on: June 14, 2022, 01:15:52 AM »
Maybe try the "Private" checkbox?

https://www.capesoft.com/docs/NetTalk11/NetTalkWebFunctionality.htm#NetWebServiceMethod

My dearest Jane,
so I knew it was there!
But when I needed it, I couldn't find it anymore. As so often.
And "Private" didn't rang any bell at me.

As always, you have hit the nail on my head!

Thank you very much.
I bow down in deepest appreciation
Wolfgang

Wolfgang Orth

  • Sr. Member
  • ****
  • Posts: 251
    • View Profile
    • oData Wolfgang Orth
Re: Service Method - avoid Documentation on some methods
« Reply #4 on: June 14, 2022, 01:19:07 AM »
yes, Private.
this is a closer "link".
https://www.capesoft.com/docs/NetTalk11/NetTalkWebFunctionality.htm#ServiceMethodSecurityTab

Bingo!

I knew it was there, but "Private" didn't say no nothing to me.

Maybe you could enhace the template promt for dumbos like me, with lets say "Exclude this Method from Documentations and WSDL".

Anyway, problem solved!

And another thank you for your Ngrok reply on my 3-P-NG-Post.


Bruce

  • Global Moderator
  • Hero Member
  • *****
  • Posts: 10758
    • View Profile
Re: Service Method - avoid Documentation on some methods
« Reply #5 on: June 14, 2022, 10:35:45 PM »
Hi Wolfgang,

I've tweaked the template to say

"Private (feel free to read the docs to see what this does)"

:)

Seriously though - I prefer to keep templates prompts as concise as is practical because there are so many of them. Trying to "document" each setting in the template leads to a very cluttered, and misunderstood interface.

But yes, you are right, there are a lot of settings, and knowing how to do everything, and what settings to use, takes time. And that's why this forum exists to help us all pool our knowledge to help each other.

cheers
Bruce

Wolfgang Orth

  • Sr. Member
  • ****
  • Posts: 251
    • View Profile
    • oData Wolfgang Orth
Re: Service Method - avoid Documentation on some methods
« Reply #6 on: June 15, 2022, 10:29:32 AM »
Hi Wolfgang,

I've tweaked the template to say

"Private (feel free to read the docs to see what this does)"

:)


Great idea!  ;D

Seriously though - I prefer to keep templates prompts as concise as is practical because there are so many of them. Trying to "document" each setting in the template leads to a very cluttered, and misunderstood interface.

yeeeees, but...!

I knew of your opinion about template prompts. On the other hand please understand our situation. We wade through these masses of template options, search for "something" of which we do not even know its name. Then I find "Private". 'Hmm, what is Private? What does it mean? Dunno. I have no time now to learn what this option is! I do not need Private,  I need to solve my problem. So where is that damned setting? I know it was there once! I know for sure!! Did Bruce remove because nobody ever used it? WHERE is that friggin' option? What can even be its name? Oh my, I better ask in the forum..."

You are right again, RTFM!

But what should I search for in the manual if I do not exactly know what to search for?
I know I want to exlude my method from the publicly visible documentaion.

Search for "documentation nettalk site:capesoft.com" returns a plethora of results.

And keep in mind many of us are non-native english speakers. Some with less, others with more accent...

I try to make my UI as verbose for users as possible. To help them in their daily work. And template dialogs are the (Clarion-)programmers daily UI.

That said, I have a slightly dofferent approach on template settings.

OTOH I do not write so many templates, so its much easier for me then for you.

But that's what my task is. Making your life difficult.....

 8)

Bruce

  • Global Moderator
  • Hero Member
  • *****
  • Posts: 10758
    • View Profile
Re: Service Method - avoid Documentation on some methods
« Reply #7 on: June 17, 2022, 04:01:58 AM »
Hi Wolfgang,

There are two ways to learn. The first is "task based". You need to complete a task, so you focus on the answer for that (ignoring all else). This is effective, but often results in asking a question, and getting an answer. That's why forums like this, and the user group webinars exist.

The other way is to work through the templates learning what everything does. This takes a lot more work, but allows you to discover things you didn't even think to ask for. For this reason there's the template documentation, along with all the other docs. I always recommend this approach because, although it takes more time and effort, results in you being a "better developer" (for some definition of better.)

This is true though not just for NetTalk. I think curiosity, and the willingness to find out, about the IDE, classes, templates and whatever else you encounter will ultimately make you a better developer. So when you see a setting, or button, or method, then I encourage developers to explore that curiosity and read up. If I see a template option, or language word then I try and stop what I've doing and investigate.

But naturally not everyone works that way, and for those who don't like exploring there are forums and webinars where you can ask the people who do. We aim to please all comers.

And, I suspect, you won't easily forget now what Private does :)

cheers
Bruce