Sorry your browser is not supported!

You are using an outdated browser that does not support modern web technologies, in order to use this site please update to a new browser.

Browsers supported include Chrome, FireFox, Safari, Opera, Internet Explorer 10+ or Microsoft Edge.

AppGameKit Classic Chat / Comments on Javadoc type program welcome.

Author
Message
paulrobson
9
Years of Service
User Offline
Joined: 22nd Nov 2014
Location: Norfolk, England
Posted: 12th Dec 2014 10:36
Hi. As a fan of documenting code I've written a javadoc type program for AppGameKit https://bitbucket.org/agkdev/agkdoc (it is free o/s). I would appreciate any comments about how this is done before finalising it.

Basically it uses an extra slash in comments (e.g. ///) to comment functions and user defined types.
Phaelax
DBPro Master
20
Years of Service
User Offline
Joined: 16th Apr 2003
Location: Metropia
Posted: 12th Dec 2014 18:10
I always liked how javadoc worked, it was so simple yet useful. Are the commands the same? Do you have a sample output of what it looks like?


"I like offending people, because I think people who get offended should be offended." - Linus Torvalds
paulrobson
9
Years of Service
User Offline
Joined: 22nd Nov 2014
Location: Norfolk, England
Posted: 12th Dec 2014 18:21
Yep, in the repository there is a demo and its HTML file.

Basically you put in things like this (I've used the C# /// type but I could make it work with /** easily enough)



And it produces a nice HTML version of the same thing - it does something very similar for user defined types.

It basically works but I thought I'd ask for feedback before giving it a bit more extensive testing and so on
unlikely
12
Years of Service
User Offline
Joined: 5th Mar 2012
Location: Ohio, USA
Posted: 13th Dec 2014 18:53
Cool man! I like it so far. Also a big fan of javadoc here.

Also, looks like you got inadvertently trolled by "Premkumar Subramanian" (@param) on your BitBucket page. Lol...
paulrobson
9
Years of Service
User Offline
Joined: 22nd Nov 2014
Location: Norfolk, England
Posted: 13th Dec 2014 19:26
Thanks. That'll teach me to just upload the README without checking.

Is there anything else I could do ? AppGameKit doesn't have classes or anything really ?
unlikely
12
Years of Service
User Offline
Joined: 5th Mar 2012
Location: Ohio, USA
Posted: 13th Dec 2014 19:48 Edited at: 13th Dec 2014 19:53
Not unless you wanted to get into some kind of "module" documenting as well. People around here seem to like to distribute libraries in "code modules," an easily importable file that contains all of the library's functionality. There could be a "module / library" documentation section with author(s), contact, version history, summary, whatever, if you wanted....

See:
http://forum.thegamecreators.com/?m=forum_view&t=210176&b=41
http://forum.thegamecreators.com/?m=forum_view&t=210460&b=41
Etc.

But I see that you are combining all of the functions / types in the project into one doc file... not sure how a "module" doc would work quite...
JimHawkins
14
Years of Service
User Offline
Joined: 26th Jul 2009
Location: Hull - UK
Posted: 14th Dec 2014 10:10
Quote: " not sure how a "module" doc would work quite..."


You need some different symbols, the way Documatic does it. Something like:

///@section///
...
///@endsection///

-- Jim - When is there going to be a release?
BatVink
Moderator
20
Years of Service
User Offline
Joined: 4th Apr 2003
Location: Gods own County, UK
Posted: 14th Dec 2014 10:42
Very useful thanks. I did the same for DBPro and it's been on my list of things to convert for a long time. I can cross it off now.

Quidquid latine dictum sit, altum sonatur
paulrobson
9
Years of Service
User Offline
Joined: 22nd Nov 2014
Location: Norfolk, England
Posted: 14th Dec 2014 18:59
It would be pretty easy to make it work for one file or selected files (at the moment it just walks the tree from wherever you run it)

Adding a @module type construct would not be a major problem either - I'll give it some thought, I think that's a good idea.
paulrobson
9
Years of Service
User Offline
Joined: 22nd Nov 2014
Location: Norfolk, England
Posted: 16th Dec 2014 15:38
I've now extended this so it has a module comment construct and also it can scan any directory or produce a document from a single source file.
unlikely
12
Years of Service
User Offline
Joined: 5th Mar 2012
Location: Ohio, USA
Posted: 16th Dec 2014 17:42
Great! That'll be a nice way for module makers to make documentation!
arnzzz
9
Years of Service
User Offline
Joined: 19th Dec 2014
Location:
Posted: 19th Dec 2014 08:31
this is fantastic.

One day i would like TGC to implement something like what IntelliJ uses, where i can mouse over a method call and if its a method i have written it'll show all my formatted javadoc, or it also can search for locale docs or online at locations i supply

I guess ive been spoiled by giant IDE's like IntelliJ when developing using Java

time to get back to "Basic".... get it, basic.....

hhmm

Login to post a reply

Server time is: 2024-03-29 07:50:58
Your offset time is: 2024-03-29 07:50:58