Application Library autodoc

Have a question about our Software Developer Kit? Ask them here.
Post Reply
User avatar
trixie
Posts: 409
Joined: Thu Jun 30, 2011 2:54 pm
Location: Czech Republic

Application Library autodoc

Post by trixie »

Considering that the Application Library chapter in the AmigaOS Dev Wiki is nearing completion, it's becoming more and more painful to see how the library autodoc lacks information or even contains errors. I know Stefan Robl has left us and cannot finish what he failed to finish. Therefore I'd like to ask who is currently in charge of developing the library. Whoever you are, I'll be glad to help you bring the autodoc out of its current pathetic state.
The Rear Window blog

AmigaOne X5000 @ 2GHz / 4GB RAM / Radeon RX 560 / ESI Juli@ / AmigaOS 4.1 Final Edition
SAM440ep-flex @ 667MHz / 1GB RAM / Radeon 9250 / AmigaOS 4.1 Final Edition
User avatar
ssolie
Beta Tester
Beta Tester
Posts: 1010
Joined: Mon Dec 20, 2010 8:51 pm
Location: Canada
Contact:

Re: Application Library autodoc

Post by ssolie »

I'm afraid a generic statement like that just doesn't help.

At this point what we need are fixes. Please feel free to update the autodocs right now and correct anything that is wrong. We can then merge your corrected autodoc changes into the source code no problem.
ExecSG Team Lead
User avatar
trixie
Posts: 409
Joined: Thu Jun 30, 2011 2:54 pm
Location: Czech Republic

Re: Application Library autodoc

Post by trixie »

@ssolie

Perhaps it's a better idea to post problems here in this very thread, instead of sending you updated files by e-mail? If people keep posting fixes here you'll have a single place to refer to, whereas e-mails can easily get lost or overlooked. Also, reading this thread other programmers can avoid problems in their code even before you release the updated autodoc with the new SDK.

OK, a report concerning the function DictGetStringForKey(). This is the current autodoc:

Code: Select all

application.library/prefsobjects/DictGetStringForKey               application.library/prefsobjects/DictGetStringForKey
   
   NAME
       DictGetStringForKey -- Get a PrefsString for a key.
       
   SYNOPSIS
       string = DictGetIntegerForKey(dict, key, defStr);
       
       CONST_STRPTR DictGetStringForKey(PrefsObject *dict,
                                  CONST_STRPTR key, CONST_STRPTR defStr);
       
   FUNCTION
       This function is a convinience function to make it easy retrieving
       a string value from a dictionary.
       If either the dict-parameter is a NULL-pointer or if there is no
       string entry stored for the given key within the dictionary, the
       default value defInt is returned.
       
   INPUTS
       dict - pointer to a PrefsObjects-dictionary
       
       key - key to search the dictionary for the boolean value
       
       defInt - default string value to return if dict is NULL or if no
       entry was found for the given key
       
   RESULTS
       string - a string
       
   EXAMPLE
       string = DictGetStringForKey(dict, "MyString", "Default string");
       
   BUGS
       
   SEE ALSO
       PrefsDictionaryA(), application.library/-prefsobjects-
Problems:

1. Wrong function name in SYNOPSIS.
2. In FUNCTION, the last sentence should read: "... the default value defStr is returned".
3. In INPUTS, the second line should read: "key - key to search the dictionary for the string value".
4. In INPUTS, "defInt" should be replaced with "defStr".
5. It should be noted somewhere that currently it is not safe to pass NULL as defStr parameter - the function will produce a DSI error.
The Rear Window blog

AmigaOne X5000 @ 2GHz / 4GB RAM / Radeon RX 560 / ESI Juli@ / AmigaOS 4.1 Final Edition
SAM440ep-flex @ 667MHz / 1GB RAM / Radeon 9250 / AmigaOS 4.1 Final Edition
User avatar
ssolie
Beta Tester
Beta Tester
Posts: 1010
Joined: Mon Dec 20, 2010 8:51 pm
Location: Canada
Contact:

Re: Application Library autodoc

Post by ssolie »

trixie wrote:Perhaps it's a better idea to post problems here in this very thread, instead of sending you updated files by e-mail?
I prefer email for fixes actually. That way I can queue them.
Problems:
I would have thought it would be much faster to just fix the autodoc text directly using a text editor instead of listing the problems one at a time. Listing the problems just introduces another layer and thus more chances for error.

Why not just cut & paste the text, edit it and send the result? I thought that would be the easiest for all concerned.
ExecSG Team Lead
User avatar
trixie
Posts: 409
Joined: Thu Jun 30, 2011 2:54 pm
Location: Czech Republic

Re: Application Library autodoc

Post by trixie »

OK.
The Rear Window blog

AmigaOne X5000 @ 2GHz / 4GB RAM / Radeon RX 560 / ESI Juli@ / AmigaOS 4.1 Final Edition
SAM440ep-flex @ 667MHz / 1GB RAM / Radeon 9250 / AmigaOS 4.1 Final Edition
Belxjander
Posts: 314
Joined: Mon May 14, 2012 10:26 pm
Location: 日本千葉県松戸市 / Matsudo City, Chiba, Japan
Contact:

Re: Application Library autodoc

Post by Belxjander »

Can the autodoc for Application Library be checked against the includes?

I've currently run into the autodoc making reference to "REGAPP_Name" and the Include doesn't define such a tag at all...

I do believe this is entirely unintentional
chris
Posts: 562
Joined: Sat Jun 18, 2011 11:05 am
Contact:

Re: Application Library autodoc

Post by chris »

Belxjander wrote:Can the autodoc for Application Library be checked against the includes?

I've currently run into the autodoc making reference to "REGAPP_Name" and the Include doesn't define such a tag at all...

I do believe this is entirely unintentional
The name is the first parameter to RegisterApplication(). As you've probably guessed, there is no need or use for a REGAPP_Name tag, which is probably why it isn't present in the includes.

@trixie
The AutoDoc will need that tag removing, if you're doing updates :)
User avatar
trixie
Posts: 409
Joined: Thu Jun 30, 2011 2:54 pm
Location: Czech Republic

Re: Application Library autodoc

Post by trixie »

@chris
chris wrote:The AutoDoc will need that tag removing, if you're doing updates :)
I'm planning to, but I'm too busy at the moment making money for my studies in England :-)
The Rear Window blog

AmigaOne X5000 @ 2GHz / 4GB RAM / Radeon RX 560 / ESI Juli@ / AmigaOS 4.1 Final Edition
SAM440ep-flex @ 667MHz / 1GB RAM / Radeon 9250 / AmigaOS 4.1 Final Edition
Post Reply