Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DNM] DOXYGEN: doxygen changes in header files 2 #2488

Merged
merged 1 commit into from Oct 5, 2020

Conversation

@b-gent
Copy link
Contributor

@b-gent b-gent commented Sep 27, 2020

Edited files in the common folder:

  • bufferedstream.h
  • callback.h
  • config-manager.h
  • coroutines.h
  • cosinetables.h
  • dcl.h
  • debug.h
  • debug-channels.h

Output is available on https://b-gent.github.io/PR2488/group__common__buffstream.html

@b-gent b-gent force-pushed the b-gent:improve_doxygen_doc2 branch from 3d3ce8b to 04cba7e Sep 30, 2020
@b-gent
Copy link
Contributor Author

@b-gent b-gent commented Sep 30, 2020

Summary of work needed for these header files:

bufferedstream.h (low priority)

Well-documented

callback.h (low priority)

I don't fully get these callbacks, I added some descriptions (please check) but the following are still missing:

  • GlobalFunctionCallback(GlobalFunction cb) (line 70)
  • Callback(T *object, TMethod method) (line 99)
  • CallbackBridge(T *object, TCallbackMethod method, BaseCallback *outerCallback) (line 141)

config-manager.h (high priority)

  • bool hasKey(const String &key) const; -> not sure how to define this 'key' and thus don't know how to document the structures that use it as an argument
    const String & get(const String &key) const;
    void set(const String &key, const String &value); (lines 129-131)

  • bool hasKey(const String &key, const String &domName) const;
    const String & get(const String &key, const String &domName) const;
    void set(const String &key, const String &value, const String &domName);
    void removeKey(const String &key, const String &domName); (lines 151-155)

  • void registerDefault(const String &key, const String &value);
    void registerDefault(const String &key, const char *value);
    void registerDefault(const String &key, int value);
    void registerDefault(const String &key, bool value); (lines 170-173)

  • bool hasGameDomain(const String &domName) const;
    bool hasMiscDomain(const String &domName) const; (lines 190-191)

  • DomainMap::iterator beginGameDomains() { return _gameDomains.begin();
    DomainMap::iterator endGameDomains() { return _gameDomains.end(); (lines 194-195)

  • void copyFrom(ConfigManager &source); (line 198)

  • ALL members of the Domain class are undocumented (lines 66-91):
    const_iterator begin() const { return _entries.begin(); }
    const_iterator end() const { return _entries.end(); }

      bool empty() const { return _entries.empty(); }
    
      bool contains(const String &key) const { return _entries.contains(key); }
    
      String &operator[](const String &key) { return _entries[key]; }
      const String &operator[](const String &key) const { return _entries[key]; }
    
      void setVal(const String &key, const String &value) { _entries.setVal(key, value); }
    
      String &getVal(const String &key) { return _entries.getVal(key); }
      const String &getVal(const String &key) const { return _entries.getVal(key); }
    
      void clear() { _entries.clear(); }
    
      void erase(const String &key) { _entries.erase(key); }
    
      void setDomainComment(const String &comment);
      const String &getDomainComment() const;
    
      void setKVComment(const String &key, const String &comment);
      const String &getKVComment(const String &key) const;
      bool hasKVComment(const String &key) const;
    

    };

courutines.h (low priority)

Overall quite well documented, especially for a low-priority header.

cosinetables.h (low priority)

Overall quite well documented, especially for a low-priority header.

dcl.h (low priority)

Well-documented

debug.h (high priority)

Well-documented

debug-channels.h (med priority)

Functions well-documented.

@b-gent b-gent changed the title DOXYGEN: doxygen changes in header files 2 [DNM] DOXYGEN: doxygen changes in header files 2 Sep 30, 2020
@b-gent b-gent marked this pull request as ready for review Sep 30, 2020
@Mataniko Mataniko requested review from sev- and criezy Oct 1, 2020
@b-gent b-gent force-pushed the b-gent:improve_doxygen_doc2 branch from 04cba7e to 1a7a0d9 Oct 2, 2020
@sev-
Copy link
Member

@sev- sev- commented Oct 4, 2020

This needs rebase now.

Edited files in the common folder:

- bufferedstream.h
- callback.h
- config-manager.h
- coroutines.h
- cosinetables.h
- dcl.h
- debug.h
- debug-channels.h
@b-gent b-gent force-pushed the b-gent:improve_doxygen_doc2 branch from 1a7a0d9 to 74bc77b Oct 4, 2020
@b-gent
Copy link
Contributor Author

@b-gent b-gent commented Oct 4, 2020

This needs rebase now.

Rebased.

@sev-
Copy link
Member

@sev- sev- commented Oct 5, 2020

Good progress, merging.

@sev- sev- merged commit c52f7e0 into scummvm:master Oct 5, 2020
1 of 7 checks passed
1 of 7 checks passed
Windows (win32, x86-windows, x86, --enable-faad --enable-mpeg2 --enable-discord --disable-fribidi... Windows (win32, x86-windows, x86, --enable-faad --enable-mpeg2 --enable-discord --disable-fribidi...
Details
Windows (x64, x64, x64-windows, --enable-faad --enable-mpeg2 --enable-discord --disable-fribidi, ... Windows (x64, x64, x64-windows, --enable-faad --enable-mpeg2 --enable-discord --disable-fribidi, ...
Details
Windows (arm64, arm64, arm64-windows, --enable-faad --enable-mpeg2 --enable-discord --disable-fri... Windows (arm64, arm64, arm64-windows, --enable-faad --enable-mpeg2 --enable-discord --disable-fri...
Details
Xcode (macosx, -scheme ScummVM-macOS, --disable-nasm --enable-faad --enable-mpeg2, a52dec faad2 f... Xcode (macosx, -scheme ScummVM-macOS, --disable-nasm --enable-faad --enable-mpeg2, a52dec faad2 f...
Details
Xcode (ios7, -scheme ScummVM-iOS CODE_SIGN_IDENTITY="" CODE_SIGNING_ALLOWED=NO, --disable-nasm --... Xcode (ios7, -scheme ScummVM-iOS CODE_SIGN_IDENTITY="" CODE_SIGNING_ALLOWED=NO, --disable-nasm --...
Details
continuous-integration/travis-ci/pr The Travis CI build failed
Details
deepcode-ci-bot Well done, no issues found!
Details
*/
template<class T, typename S = void *> class Callback: public BaseCallback<S> {
protected:
typedef void(T::*TMethod)(S);
T *_object;
TMethod _method;
;

This comment has been minimized.

@sev-

sev- Oct 5, 2020
Member

That broke the compilation horribly, for obvious reasons.

This comment has been minimized.

@b-gent

b-gent Oct 5, 2020
Author Contributor

To be honest, I was assuming we would still be working on this PR, at least adding missing doc in the high-priority headers. Hence the 'Do Not Merge' label in its title.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

2 participants
You can’t perform that action at this time.