Forums Developers mIRC Documentation Idea

Ok before anyone goes and says this is spam, let me first say that I asked a moderator whether it would be ok if I posted this, and I was told I could.

One of the biggest problems with mIRC scripts is their lack of documentation, and even when people write documentation, they write it in very different forms. Some include it in a help.txt, some in the comments within the .mrc, some don't include it at all. Basically, what I came up with is something called mIRCDoc (modeled heavily off of Javadoc) to correct these problems. mIRCDoc will introduce a standard method of writing mIRC script documentation, and it will do it in a format that can either be viewed by a person, or easily parsed by another script that can convert it to whatever format you want (HTML, txt file, etc.). The idea still needs a lot of work and refinement, but I was wondering if anyone here would like such an idea, and if people would be willing to make suggestions and/or support such an idea.

If you are interested the current version of my idea is available at http://www.codemastr.com/mircdoc.html. As I come up with ideas, or as people make suggestions I'll try and keep that updated.

Hmm. Nice thought at the move towards standardization... but I think scripts vary so dramatically that such a standard is impossible to satisfy both large scripts and small scriptlets, let alone combinations of these.

Another problem is when you put all this in one location, it because that much easier to rip (not include) or modify in redistribution. I'm quite happy with the many nonstandard current methods that scripters use in embedding comments in various places through out script files, just as long as they include SOME documentation. For those scripters who currently do not, this wont break their bad habits.

Suggestions like this have also been made in the past. Once I tried outfitting all of my script files with a version identifier that could [almost] be enumerated through with this single alias in each file.

ALIAS ScriptInfo {
; Gets the script's current load position. Something $script(filename) should do.
var %i = 1 | WHILE $script(%i) { if ($script == $ifmatch) { break } | inc %i }
if ($1 isnum) && ($1 != %i) {
return $ScriptInfo($1-)
}
elseif ($1- != $script) {
return $ScriptInfo($1-)
}
if ($prop == name) return Jupe Script
if ($prop == version) return 1.0
if ($prop == author) return Raccoon
if ($prop == longname) return Jupe Script v1.0 By Raccoon
if ($prop == desc) return Holds onto your nickname.
if ($prop == instructions) return /Jupe [On|Off] [[-]Nickname(s)]
if ($prop == file) return $script
if ($prop == order) return %i
}

It use to work somewhat well when recursion was not at all possible, because it would [almost] keep on calling the next $ScriptInfo identifier available in the next script file, until it finally hit the right one. It would be nice if this really would work someday, but it's not of any significant importance.

- Raccoon

People said the same kind of thing when Java adopted Javadoc, however now almost all Java programmers use Javadoc. To say it is "impossible" to satisfy all scripts really has no basis. As I said, it is being based on a documentation scheme that does do it. So if it is based on one where it is possible, why would it be impossible here? As I said, it's far from perfect right now, but thats why I'm asking for suggestions. It can be done, it's just a matter of will it be done. If it were up to me, yes it would. But to suceed, others need to support it. I mean look at things like MTS. I thought it would fail miserably. But in reality it has become the de facto standard for creating themes in mIRC. Why can't the same thing occur here with documentation? If anything, MTS proven that if people in the mIRC community work together, they can accomplish standardization.

As for some people not using it, you're right, they probably won't use it if they don't do documentation now. But is that really a reason not to do something? A standardized, parsable documentation format is beneficial to both users and coders. Coders can now easily include the documentation right in the script code, which is very useful in large scripts. When you have 500 aliases in a single file, it's very easy to forget the syntax for each one. mIRCDoc makes it so the documentation is right there, and if you don't want to look through the file to find it, just use something like my /getdoc command which will give you the information instantly. Also, documentation never has to be duplicated. You know how many times I've seen projects (both mIRC scripts and regular programs) where the docs that come with the application don't match the ones on the website? People forget they have multiple documents that need to be updated. Then when they remember, they forget which part actually changed. mIRCDoc solves that as well. You simply would do something like /mircdoc2html and it would convert the mIRCDoc comments to an HTML format.

I agree, something like this will be difficult to get working fully, but since when is the fact that something is hard to do a reason not to do it? If you ask me, it's a challenge, and why not try and overcome the challenge rather than backdown? And even once it is fully working, it will be even harder to have it adopted, but again I refer to MTS, while you would be right in saying most people didn't recode their own theme engines to work with MTS, the people who were writing new themes did use MTS. And eventually, maybe years from now, the only themes available will be MTS themes. Why can't the same hold true here? Maybe everyone won't quickly go and reformat their documentation, but maybe people who are writing new scripts will use the format in those scripts. And eventually, the older scripts will have faded away.

I've already got a similar system in my script and it surelly is a good idea to keep up with all the commands and identifiers we create. My code actually builds a XML database file that can then be parsed like I wish.

OI!

mircscripts.org -> IDEmIRC - > the mircDD bit

Ah HAH: I thought I'd lost it coz the provider mangled my site (yet again), but no: http://users.quickfox.tk/~clockwerx/main.php?page=tutorialMEARdoc

Basically I already did this, suggested this, and got summarily ignored.

the basic syntax I had going was:

;public aliasname, aliastwo, etc

and mIRCDD reads the script file for ;public *, pulls out all the aliases from that, and calls them.

alias aliastwo {
;description blah blah <b>blah</b>
;syntax /aliastwo <blag>
;returns null

var %description = blah blah <b>blah</b>
var %syntax = <blag>
var %returns = null

if ($prop == description) || ($prop == syntax) || ($prop == returns) {
return $eval($+(%,$prop),2)
}

;rest of code here


}

there's a snippet on mircscripts.org which reads comments BELOW or ABOVE a script entry, so its compatible with that.

One of the original ideas for the mear site is to write a PHP document generator that picks out the
;description comments
;returns here

etc... creating an online archive of documentation that is updated dynamically (whenever someone calls it for the version of the file)...

I've also written a dialog based help viewer for the mear framework, which uses the $aliasname($null).syntax $aliasname($null).description
etc, creating a dynamic online help system for the script.

*edit*
instead of competing you want to discuss this so that we can integrate the two methods (one standard then..)?
If so feel free to priv me...
It'd be like EMCA (ECMA?) script wars - Microsoft vs. Netscape implementations of javascript (Jscript) if we didn't...
I'm working on a lot of mIRC related tools, such as a script parser for websites, that checks basic syntax, missing brackets, etc. Its not perfect but its nice. It'd stop scripts from being mangled at a lexical level...
This plus the 'documentation center' PHP code would make things nice and purdy in terms of standardisation.

Wel imho the idea of using $prop is a very bad idea. Why? When mIRC reads a script, it strips the comments, they are not loaded in memory. However, all that $prop stuff is. That means each time someone uses the alias mIRC has to check if $prop == any of those strings. Why should we make the script slower to have documentation?

If anyone actually cares, I've made some changes to reflect some of the ideas that the people who responded suggested. The biggest change is "per script" documentation. Meaning you can have documentation associated with each alias, but now you can also have documentation associated with the entire file (such as author, copyright, etc.).

I was never concerned with ripping I always comment my code. Then include a plain ascii *.txt with it describing the wonderful intracacies it helps me keep things in order as well. no frills stick with ascii.

Ripping? This idea has nothing to do with preventing ripping.