libinkview documentation

[sergeyvl12]

Hi!

libinkview documentation project started!

Related topic at the-ebook.org

Join our project!

Google code page: http://code.google.com/p/libinkviewdoc/

Documentation example: http://pbsdk.vlasovsoft.net/html/inkview_8h.html

In this example only 2 functions are documented: PartialUpdate() and PartialUpdateBW(). Use search in the top-right corner to find a function by name!

[rkomar]

Thank you for getting this going! I've already learned what "BW" stands for in the function names (unbelievable that I didn't guess it before). How does one join the project?

I think it would be good to connect the defines with the function flags they are used for. I also have some experience now with using threads with Inkview applications. It would be good if we had some Wiki space for sharing experiences and advice.

[MartinZ]

The next try....

Meesa Yousa started something like this already:

openbookus

And

yann did it before for 14.1 SDK

http://donkey.vernier.se/~yann/pbapi/doc/html/

And I suggested to continue this in the German thread here and I already created a partially commented, Doxygen-compatible inkview.h on my HD...

Of course I support your (hopefully finally successful) try and again thak you for your big work on SDK and now also on dokumentation.
I would really like to help:

Could you please tell us briefly, how the "workflow" has to be done on your site
http://code.google.com/p/libinkviewdoc/source/browse/
?

Do I have to download:
http://code.google.com/p/libinkviewd...owse/inkview.h
add or change comments and upload it back, or how does this work?

cheers, Martin.

[sergeyvl12]

Originally Posted by MartinZ

The next try....

I was in Kiev (PocketBook conference) and PB promised to turn it's face to us. We''ll se. Now thay became are close to us and I'll ask thay to help us with documentation (will be good if they give a developer to support us).

Originally Posted by MartinZ

And
yann did it before for 14.1 SDK

Ok, thanks, we will use his work.

I suggest that we have a central storage (mercurial repository). And every developer that wants to join our project can:

1. clone this repository;
2. make his changes;
3. push his changes back to the central repository.

Originally Posted by MartinZ

And I suggested to continue this in the German thread here and I already created a partially commented, Doxygen-compatible inkview.h on my HD...

Nice! we can merge our work!

Originally Posted by MartinZ

Could you please tell us briefly, how the "workflow" has to be done on your site
http://code.google.com/p/libinkviewdoc/source/browse/
?

Our workflow will be:

1. Register at google code http://code.google.com/
2. Join to our project: http://code.google.com/p/libinkviewdoc/
3. Install mercurial (source control tool) in your linux environment
4. Add something like that in your ~/.hgrc:

[ui]
username = Sergey Vlasov <vlasovsoft@mail.ru>

(your email)

5. Login to google code, find our project
6. Use "hg clone <url>" to clone this project (makes local copy on you HD); You'll se the URL for read/write when you login;
6. Make some changes ...
7. Use hg commit -m "message" to commit your change to your local repository;
8. Use hg push <url> to transfer your changes to central repository.
9. I'll rebuild the documentation weekly.

[sergeyvl12]

Originally Posted by rkomar

Thank you for getting this going! I've already learned what "BW" stands for in the function names (unbelievable that I didn't guess it before). How does one join the project?

See my instructions above

Originally Posted by rkomar

I think it would be good to connect the defines with the function flags they are used for.

I think doxygen will allow us to do it.

Originally Posted by rkomar

I also have some experience now with using threads with Inkview applications. It would be good if we had some Wiki space for sharing experiences and advice.

Sure. I hope, documentation is the very first step.

[rkomar]

Originally Posted by sergeyvl12

See my instructions above

I have looked around the project site, but haven't found any way to join. Am I supposed to send you an E-mail to get commit privileges? Or would you just prefer patches?

[sergeyvl12]

Originally Posted by rkomar

I have looked around the project site, but haven't found any way to join. Am I supposed to send you an E-mail to get commit privileges? Or would you just prefer patches?

Sorry, I've forgotten that I should manually add you to project. Please send me your email (your login to google code) and I'll add you.

[sergeyvl12]

MartinZ,

I just see you 2 issues. I'll merge them to inkview.h soon.

Btw...

How can I apply your patch to my inkview.h?

O, nice ...

patch -p1 < inkview.h.patch

I've committed your patches! Thanks, great job!

I noticed that we have different comments format. I think we have to use single format. As for me, the format "//!" is ok.

[MartinZ]

I noticed that we have different comments format. I think we have to use single format. As for me, the format "//!" is ok.

That's not "my" format, but I follow the syntax given by Doxygen.

Doxygen let's us steer the documentation, that it generates from the .h-file.

We can define groups, comment functions and their parameters and return values and a lot of more things.

For this Doxygen requires a certain way of commenting. I looked some techniques up in the Doxygen manual and used it this way.

If our aim is to have a Doxygen-generated html-documentation, we have to stick to Doxygen's syntax.

But you could suggest, which set of doxygen comments we should use and which one we should avoid, to get a homogen and smooth documentation-style.

by the way:

shouldn't it read "\brief" and not "\breaf" ?

[sergeyvl12]

Originally Posted by MartinZ

That's not "my" format, but I follow the syntax given by Doxygen.

Doxygen let's us steer the documentation, that it generates from the .h-file.

I meant "commenting style". There are several "styles" in doxygen.

I saw that your style is "//!". My style was "/*!"

I've converted all to "//!".

Originally Posted by MartinZ

But you could suggest, which set of doxygen comments we should use and which one we should avoid, to get a homogen and smooth documentation-style.

"//!"

Originally Posted by MartinZ

by the way:
shouldn't it read "\brief" and not "\breaf" ?

Thanks! fixed.

BTW. I've updated my pbsdk site. Now it refers to documentation. But documentation main page is empty!

http://pbsdk.vlasovsoft.net/html/index.html

We should add something to the main page...

[sergeyvl12]

Events handling section added. But not everything is clear ... Please review

[MartinZ]

Hi developers,

1) I added / unified groups and subgroups and added comments (most of them like commented in yann's 14.1 documentation)

2) I changed doxfile so we get a treeview left side screen in doxygen - generated documentation

3) I used grouping scheme:

 //! \defgroup Groupname Description 
  //! \{

  //! \}

or

 //! \addtogroup Groupname  
  //! \{

  //! \}

for the main groups like "Graphics"

and

 //! \defgroup Groupname Description 
  //! @{

  //! @}

or

 //! \addtogroup Groupname 
  //! @{

  //! @}

"@" and "\" do the same - but this way you can see directly that "@" includes subgroups.

and I used

//! \name Description
//! @{


//! @}

for additional structuring.

[sergeyvl12]

MartinZ, thanks! Great job!

I'll publish this version of docs on pbsdk.vlasovsoft.net.

[MartinZ]

Hi Sergey,

1.) Could you put a link to the html-documentation, that you host on your site to the google-code-project page?

2.) I think it would be quite helpful if we could link some example code to the functions and structs explanations.

3.) Thanks for latest comments on timer and sleep functions.

Greetings,
MartinZ

[sergeyvl12]

Originally Posted by MartinZ

Hi Sergey,

1.) Could you put a link to the html-documentation, that you host on your site to the google-code-project page?

sure

Originally Posted by MartinZ

2.) I think it would be quite helpful if we could link some example code to the functions and structs explanations.

Yes, we can...

The 2 options are here:

1. Examples inside the docs:

//! \code
//! case EVT_KEYRELEASE:
//! {
//! printf("Before SendMessage()\n");
//! SendEvent(main_handler, 2000, 0, 0);
//! SendEvent(main_handler, 2000, 0, 0);
//! FlushEvents(); // the 2 pending events are not processed immediately... why?
//! printf("%d\n", IsAnyEvents()); // result is 1 ... why?
//! }
//! \endcode
//!

2. Examples outside the docs.

I prefer the first way... What about you?