Wiki reviews

[GoogleCodeExporter]

Each time you change something in the wiki, it generates a next review, 
but you can't edit code AND at the same time post wiki changes with that.

I don't mind showing wiki changes it up in updates, but I do mind the 
review change, is there a way to deactivate that? Or may there is a way to 
change code and wiki in one step?

Original issue reported on code.google.com by goo...@teabix.com on 29 Nov 2009 at 6:19

[GoogleCodeExporter]

If this wikie-code synch is not possible, I also suggest making the wiki a 
html/css 
part of the SVN. This way:
- you can change the HTML and Code, and commit everything in one review.
- it makes offline-documentation possible.
- the rigth documentation get's published with the right release. (now, Beta 
2.1 is 
not usable anymore, since there is no documentation, because wiki is too 
updated)
- quite same as previous. Currently, people might get confused, because the 
wiki is 
even more updated than the last featured release.

Original comment by goo...@teabix.com on 29 Nov 2009 at 11:45

[GoogleCodeExporter]

It's already part of the SVN.

https://bwapi.googlecode.com/svn/wiki/

Original comment by AHeinerm on 3 Dec 2009 at 11:47

[GoogleCodeExporter]

Original comment by lowerlo...@gmail.com on 7 Dec 2009 at 1:12

• Changed state: Questionable

[GoogleCodeExporter]

Original comment by lowerlo...@gmail.com on 7 Dec 2009 at 6:09

• Added labels: Type-Enhancement

[GoogleCodeExporter]

Original comment by lowerlo...@gmail.com on 7 Dec 2009 at 6:14

• Added labels: Priority-Low

[GoogleCodeExporter]

I don't agree with committing the wiki via code or anything Google related. 
Rather,
PLEASE document all the headers Doxygen style. This has the following benefits:

  * Generated documentation is present in the release so people don't have to
question why something appears to appear in the wiki but not their version.
  * Wrapper writers (such as myself) can auto generate their documentation from yours
per release.
  * You can easily show developers when a method was implemented (i.e. @since). This
is a HUGE help for wrapper developers that want to explain version differences 
and/or
preserve backwards compatibility
  * Developers can see what documentation changed from version to version. So when a
method signature doesn't change but what it performs does, everyone will know.
  * This follows common volatile C++ library conventions. Documentation should be
visible per release to say the least.

Of course, some of the above can be arguments for proper tagging and/or source
releases, but that's a different issue.

Original comment by chad.r...@gmail.com on 7 Dec 2009 at 7:38

[GoogleCodeExporter]

Header documenting is a good idea as long as the documentation contains text. 
drawText has already an image and I'm sure there are more to come. If there is 
a way 
to add images to header comments (relative links ofcourse, they should get 
correctly 
converted to images when generating the wiki), then I endorse header comments, 
keeps 
the project DRY.

Original comment by goo...@teabix.com on 7 Dec 2009 at 10:56

[GoogleCodeExporter]

http://www.stack.nl/~dimitri/doxygen/commands.html#cmdimage FTW

Original comment by chad.r...@gmail.com on 7 Dec 2009 at 6:44

[GoogleCodeExporter]

See the 1_Function, google's wiki automatically linked keywords to BWAPI2 
topics. 
This will confule users. Additionally, online help is not too practical as is. 
A 
separate and deployable documentation means would help, especially for browsing 
the 
documentation offline.

Ever tried programming with DirectX? It's offline help is really satisfying for 
it's 
speed and convenience. Windows documentations are all distributed as .chm 
files. 
Apparantely they can be compiled from HTML with a free microsoft tool called 
HTMLHelp Workshop. (All linux users gasping out there: there are tools to view 
.chm 
files on linux.). I also found a way to automate the compiling process so you 
don't 
have to deal with the retardet UI of HTMLHelp workshop.

Later, if needed, the .chm can be generated by doxygen, although I very doubt 
doxygen will be appropriate for BWAPI1 in particular... (from what I've seen I 
was 
greatly discouraged).

I made a preview. Created a microsoft-doc-similar style sheet and fully 
documented 
the BWAPI1::Connect function. File appended, note that it may not work if you 
start 
the .chm directly from the .zip, you should first unpack it.

Original comment by goo...@teabix.com on 5 Jan 2010 at 12:17

Attachments:

• Example1.zip

[GoogleCodeExporter]

The only alternative to .chm (if you oppose it too much) I see is to move 
BWAPI2 to 
a separate google project, so each has it's own wiki and an own pagespace in 
general. As side-effect this would provide a clear way to deal with BWAPI and 
BWAPI2 
users separately.

Original comment by goo...@teabix.com on 5 Jan 2010 at 6:39

[GoogleCodeExporter]

I don't know if forking the project is best. I'd still take the doxygen 
approach.
Then commit the docs w/ the project. You can then set the svn:mime-type to 
text/html
and you can link to the docs directly. Example:
http://bwapi-jbridge.googlecode.com/svn/tags/0.2-alpha/bwapi-bridge/etc/docs/api
/index.html.

Original comment by chad.r...@gmail.com on 5 Jan 2010 at 7:15

[GoogleCodeExporter]

For BWAPI1 you'd have more conditinal doxygen code flying around than actual 
documentation, and the BWAPI1 structure is not a traditional 
classes-and-methods 
one, but a data oriented one with several topics that do not even correspond to 
any 
code in particular. Doxygen output are too verbose and object oriented to be of 
use.

For BWAPI2 doxygen would be an appropriate solution, but BWAPI2's documentation 
is 
lowerlogics realm and his decision.

-"I don't know if forking the project is best."

I don;t know either ;) any particular arguments?

Original comment by goo...@teabix.com on 5 Jan 2010 at 7:29

[GoogleCodeExporter]

Original comment by AHeinerm on 28 Jan 2010 at 9:54

• Added labels: Component-Docs

[GoogleCodeExporter]

This has been questionable for too long. Cleaning up.

Original comment by AHeinerm on 8 Feb 2010 at 10:07

• Changed state: Invalid