Bad Docs

I don't have any clue why almost every piece of software has bad documentation like everywhere. Its either bad documentation or bad access to documentation.

This is prevalent even in fields like console development, there you will find areas of the console be documented very meticulously however other areas are left as an essential "Left as practice for the reader". It seems so very absurd to very blunt.

so why am I talking about bad docs? well here is the deal. I use vim for my programming, I also heavily lean towards pure C because of the simplicity. Given vim doesn't have a build & run cycle as buttons you need to implement them yourself.

For me this shows up as a tools.bat file which takes a few arguments. If you double click the file, it will open up a command prompt, call vcvarsx64.bat and open a gvim window. This essentially gives a gvim instance that has access to cl.exe and msbuild tools to build your programs.

For my build system I use Sharpmake and generate my projects using simply tools.bat make. On the vim side of things I use Vim-Dispatch plugin to run the tools.bat file, it makes life so much easier as Vim-Dispatch will use the job system to create a separate instance of the command prompt and run the tools.bat file. It will also pipe the output from the ran application to vim's quickfix menu.

Once a project is generated tools.bat build will build it and tools.bat run will run this executable. If you have your errorformats setup correctly for Vim-Dispatch both build and run can give you easy jump lists to your files. Life is happy, everything moves on.

However Vim-Dispatch has a flaw, because it uses jobs from vim, everything is async so you can get into a situation where you can re-run your executable twice without the ability to kill one of them.

You can only ever kill the latest job that Vim-Dispatch is aware running, this is annoying when you are testing stuff like sockets and server/client code.

Small Scripts

I wanted to write a small script to get all the jobs that I have running via vim jobs and kill them all. I never saw if this was possible or not, I looked at vim's docs multiple times.

If you do a :h jobs it jumps to essentially job_start, you can search around and find job_status and job_stop, job_stop is what I'm looking for but it requires a job handle which we don't have.

I looked around a bit more for a job_list function, no such thing exists. I also found job_info which seems to be also something like job_status. It was only ever today that I saw that there is a line under job_info that says without an argument it will return the list of all job objects.

I started writing a small function:

def! g:GetAllAliveJobs(): list<job>
   var all_jobs = job_info()
   var alive_jobs = []
   for j in all_jobs
       if j->job_info()['status'] != 'dead'
           alive_jobs->insert(j)
       endif
   endfor

   return alive_jobs
enddef

def! g:KillAllJobs()
    var alive_jobs = g:GetAllAliveJobs()
    for j in alive_jobs
        job_stop(j)
    endfor
enddef 

Very simple and straight forward to write this and it kills all the jobs!

That one line in job_info was something I never saw! because I was just glancing through the code! I wonder if there was a Note in front of it or some other highlighted aspect it would have been more apparent.

Either way write better documentation and write smaller scripts to help make life easier.