SDK Reference Manual

[takeshimiya]

UPDATE here: http://forums.next.codeblocks.org/index.php/topic,1358.0.html

Hi!

I was reading that a SDK documentation is needed, and I can't help writting one as I don't know how the plugin system works.

But I noticed that the commentaries in the code of Code::Blocks are more or less doxygen friendly. So I've made (at least as a proof of concept) a reference manual of the SDK using DoxyS (a doxygen spin-off).

It needs a lot of improvement, but I think that is on the good way.
The more things that it needs, are examples and hand-written text (more like a book rather than a reference). I'm worried that I can't help with that (rickg22? )
It also have some bugs, but as DoxyS is in active development isn't such a problem.

See build_docs/README.txt inside "codeblocks-1.0-finalbeta_sdk-build_docs.zip"

Hope you like it.


HTML manual:
http://www.kaze-fansub.com.ar/basura/takeshimiya/cb/codeblocks-1.0-finalbeta_sdk-html.tar.bz2

CHM manual:
http://www.kaze-fansub.com.ar/basura/takeshimiya/cb/codeblocks-1.0-finalbeta_sdk-htmlhelp.zip

How I built that:
http://www.kaze-fansub.com.ar/basura/takeshimiya/cb/codeblocks-1.0-finalbeta_sdk-build_docs.zip

[takeshimiya]

Please reply, else I feel useless here.

[tiwag]

well done, thanks !

[rickg22]

Thanks! However I bet many windows users (i.e. moi)  would also like those CHM's in ZIP format. (You're a linux user, right? ;-) )

[takeshimiya]

haha, no, I'm a windows user, but I thought the opossite,
as it's more easy to open a tar.bz2 in windows than opening a zip or rar in linux.
ie. Winrar or 7-zip decompress tar.bz2 files easily.

Anyways the other reason is space, compare yourself the size of the html version in the bzipped ver. vs. a zipped ver.
-HTML manual zip'ed: 6.60 MB (Winrar doesn't let me choose "solid archive" for zip)
-HTML manual bzip2'ed: 1.02 MB
-HTML manual 7zip'ed: 839 KB (but isn't very standard yet)

Also I thought that the .tar.bz2 was THE standard in all opensource projects.

Ok, enough talking, here it's the CHM manual in ZIP format:
http://www.kaze-fansub.com.ar/basura/takeshimiya/cb/codeblocks-1.0-finalbeta_sdk-htmlhelp.zip


Anyways, if do you like it, please see the section "Current bugs" in README.txt
(Yiannis or rickg22 read it please and tell me what do you think about that).

[rickg22]

Wow, it's FANTASTIC! This file should be included in the SDK releases!

[mandrav]

Very nice work, takeshimiya

Yiannis.

[takeshimiya]

I'm glad all of you liked it


Now, for the improving part:

I've found these bugs:

Current bugs of DoxyS
-----------------------------------------

- Doesn't support text formatting on brief descriptions (not very important).

- The function parameter documentation ///< works well on .h but not on .cpp files.


Current bugs of the C::B comments
-----------------------------------------
- For example on cbplugin.h, at the
virtual void BuildModuleMenu() function, the behaviour of DoxyS is always to take
the brief description from the first line (ie. you don't need @brief or \brief),
but if you are used to, it's better to put the cmd @brief then.

- Also always remember to put /// instead of // to document the code, for
example not like on "compiler.h" at the struct RegExStruct.

- Also try to remember when documenting variables in structs or classes:
int m_iMemberVarShortDoc; ///< Short single line documentation
instead of
int m_iMemberVarShortDoc; // Short single line documentation

- Documenting what is not documented =)


-----------------------------------------
I would like to fix the "C::B comment bugs" but I don't have CVS access (I never used CVS).
Anyways some are easy to fix (most of them are a replace from // to ///),
So Yiannis or rickg22, who do you recommend to fix them?

[mandrav]

I will do this. I 'm gradually adding documentation to as-yet-undocumented base SDK classes anyway.

Yiannis.

[takeshimiya]

Great , then the only thing left are the examples and hand-written text.

rickg22 or anyone that knows well how the SDK works, when you find the time, try to make some examples (either in cpp/h very commented or in a plain txt), and some explanation of basic things (like a quick start).

Well, I think that's all to have a helpful sdk manual. =)

[heromyth]

Learning!
Thanks!

[rickg22]

OK let's see....
There's the Manager classes. EditorManager, ProjectManager, MessageManager, PluginsManager

These managers overall form the "core" of Codeblocks, everything's around them. Editormanager handles the openfiles tree and the files closing, saving, loading, etc. Look for cbEditor and Editorbase, too.


Projectmanager deals with the project tree, the projects, workspace, etc. (Look for cbProject, cbWorkspace)

MessageManager is the message pane with lots of tabs.

PluginsManager handles the plugins loading. (see cbPlugin)