Talk:Development: Documentation

Hi Francesco,

As a potential user, I have some suggestions about the design of Interface checking utility.

It's better to develop a group of useful classes (which might be put in wxWidgets later) during developing this util.

The classes will focus on classes, member functions etc. and disgard any unrelevant implementation details.

Here is a rough illustration of the classes with only the interface.

class wxCPPHeaderParser
{
    public:
        wxCPPHeaderParser(wxString headerFileName);
        wxCPPHeaderParser(wxFile & headerFile);
        //wxCPPHeaderParser(wxInputStream & headerFileString);

        /** In order to locate the header included for general usage**/
        SetEnvironmentVariable(wxString path);
        /** In order to parse the included file for general usage.
        This util won't need it.**/
        wxCPPHeaderInclude * GetNextInclude();


        /** I realized that there is no need to have a getfirst function, since
         for the first call of getnext is getfirst**/

        //wxCPPHeaderDefine * GetFirstDefine();
        wxCPPHeaderDefine * GetNextDefine();

        //wxCPPHeaderEnum * GetFirstEnum();
        wxCPPHeaderEnum * GetNextEnum();

        //wxCPPHeaderClass * GetFirstClass();
        wxCPPHeaderClass * GetNextClass();

        //Global variablea
        wxCPPHeaderVariable * GetNextVariable();

        //Global functions
        wxCPPHeaderFunction * GetNextFunction();

        //...
};

//Some flags can be combined, some can't
enum wxCPPHeaderFunctionType
{
    wxHF_GLOBAL,
    wxHF_STATIC,
    wxHF_CREATOR,
    wxHF_PUBLIC,
    wxHF_PRIVATE,
    wxHF_VIRTUAL,
    wxHF_CONST
};

class wxCPPHeaderClass
{
    public:
        wxCPPHeaderClass(wxString classname);
        wxString GetClassBase();
        wxString GetClassName();
        //...
        void AddFunction(wxCPPHeaderFunction * function);
        wxCPPHeaderFunction * GetNextFunction(wxCPPHeaderFunctionType flag = wxHF_PUBLIC);

};

class wxCPPHeaderFunction
{
    public:
        wxCPPHeaderClass * GetClass();
        wxString GetReturnType();

        bool IsStatic();
        bool IsVirtual();
        bool IsPublic();
        bool IsConst();

        wxCPPHeaderFunctionParameter * GetNextParameter();
        //...
};

class wxCPPHeaderFunctionParameter
{
    public:
        wxString GetType();
        wxString GetName();
};

//...

Regards,

Utensil

-- reply by Francesco: sorry about it, but ifacecheck utility has already been written a while ago with a different approach (i.e. that of not reinventing the wheel, a complex wheel in this case!!, and rather use already existing c++ parsers). I've updated the main wiki page to reflect the new advances regarding that utility.

Reporting Individual Documentation Errors

Under the section How can I help? a few lines should be added for users who come across documentation errors in the course of their work. Programmers employing a current stable version of wxWidgets might find areas which need improvement. How can they be sure that those problems are cleared? They might not have the SVN trunk available but should be cautioned to refer to the current documentation. (https://docs.wxwidgets.org/trunk/)

Where is the best place to report a problem? Trac? A mailing list? The forums? Guide the casual user who might come across this Development: Documentation page. Perhaps a link to the http://trac.wxwidgets.org/wiki should be included.

The reviewers listed in the Task List should be reliably notified lest they miss a small error. (Mine eyes doth glaze over.) --Cmb 17:38, 24 May 2008 (UTC)