[CONNECT C++] MSDialog::GetItemPtrByTypeAndId Documentation

I can find below descriptions from header file MSDialog.h

/*----------------------------------------------------------------------------------+
    * @description Returns an item pointer specifically for the given item type and resource 
    * ID of the item contained in this Dialog Box.
    * The list of possible values for type is contained in dlogbox.r.h.  For example, the 
    * type of a text item is RTYPE_Text.
    *
    * @code
        pTextBox = GetDialog ()->GetItemPtrByTypeAndId <TextBoxP> (RTYPE_Text, TEXTID_Example, 0);
    * @endcode
    +----------------------------------------------------------------------------------*/
    template <typename T>
    T GetItemPtrByTypeAndId (RscType type, RscId id, MdlDescP ownerMD = NULL, int startingIndex = 0, bool searchChildren = false)
        {
        DialogItemP diP = GetItemByTypeAndId (type, id, ownerMD, startingIndex, searchChildren);
        if (NULL != diP)
            return diP->GetTypePtr <T> (type);
        else
            return NULL;            
        }

Yongan.Fu said:

I can find below descriptions from header file

Yes — I can find that too!

I posted this because the comments in the header file have been omitted or corrupted by the Bentley doc generator.  The MicroStationAPI help doesn't make sense.  This comment in help is particularly bewildering...

References GetItemByTypeAndId(), and NULL.

When I post about the SDK help documents, it's often because the docs are incorrect or don't make sense. Sometimes, as in this case, the Bentley doc generator has probably become confused because of the template declaration of this function: template <typename T> is misinterpreted.

As an experienced developer, I know where to look to find more accurate information.  My continuing battle with Bentley is to highlight parts of the documentation that are not helpful.  If you want to attract independent developers to the Bentley platform, it's bad practise to present them with poor documentation.

By the way, GetTypePtr() has a similar problem...

T GetTypePtr  ( RscType  itemType )  
References NULL, and type

Filed below defect for this. Thanks for your report.

Defect 1127466:MSDialog::GetItemPtrByTypeAndId doc messed up