[mapguide-users] EXTERNAL_API not documented in doxygen

[Jim O'Leary]

Thank you Bruce.

For me it was confusing when learning the Web API that the siteconnection
class has an open method but the site does not (that is, I could not see it
in the doxygen output). Probably most developers who are starting to learn
the Web API would be like me; they would not think of going to the C++ code
to find out about the site class. That is my only concern.



Bruce Dechant wrote:
> 
> There are 3 defines that control what ends up in the API and what is
> documented.
> 
> 1) PUBLISHED_API
>    - These APIs are documented and officially supported.
> 2) EXTERNAL_API
>    - These APIs are NOT documented because they are NOT officially
> supported and may be removed in a future release without warning.
>    - Some of these APIs may end up as "PUBLISHED_API" and officially
> supported in a future release.
> 3) INTERNAL_API
>    - These APIs are not exposed in the web tier.
> 
> Thanks,
> Bruce
> 
> -----Original Message-----
> From: mapguide-users-bounces at lists.osgeo.org
> [mailto:mapguide-users-bounces at lists.osgeo.org] On Behalf Of Jim O'Leary
> Sent: October 27, 2007 3:10 PM
> To: mapguide-users at lists.osgeo.org
> Subject: [mapguide-users] EXTERNAL_API not documented in doxygen
> 
> 
> Is there a good reason why some public methods are not documented in the
> doxygen output for MGOS? For example, in a typical code sample I see:
> 
> $site = new MgSite();
> $site->Open($userInfo);
> 
> These methods are not documented in the doxygen output, which could be
> confusing if you are trying to understand the code. However, in the source
> code at:
> 
> Common\MapGuideCommon\Services.Site.h
> 
> I see:
> 
> EXTERNAL_API:
> 
> 
> ///////////////////////////////////////////////////////////////////////////////////
>     /// \brief
>     /// Construct an MgSite object and open a connection to the Site
> Server.
>     ///
>     /// \return
>     /// Nothing
>     ///
>     MgSite();
> 
> 
> ///////////////////////////////////////////////////////////////////////////////////
>     /// \brief
>     /// Opens a connection to the Site Server.
>     ///
>     /// \param userInformation
>     /// User information to authenticate against
>     ///
>     /// \return
>     /// Nothing
>     ///
>     /// \exception MgNullArgumentException
>     /// \exception MgAuthenticationFailedException
>     /// \exception MgConnectionFailedException
>     ///
>     void Open(MgUserInformation* userInformation);
> 
> ...and other methods. So it appears that code that is under EXTERNAL_API
> does not make it into doxygen.
> 
> Thanks.
> --
> View this message in context:
> http://www.nabble.com/EXTERNAL_API-not-documented-in-doxygen-tf4704536s16610.html#a13447448
> Sent from the MapGuide Users mailing list archive at Nabble.com.
> 
> _______________________________________________
> mapguide-users mailing list
> mapguide-users at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/mapguide-users
> _______________________________________________
> mapguide-users mailing list
> mapguide-users at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/mapguide-users
> 
> 

-- 
View this message in context: http://www.nabble.com/EXTERNAL_API-not-documented-in-doxygen-tf4704536s16610.html#a13536296
Sent from the MapGuide Users mailing list archive at Nabble.com.