Hi everyone, I've been quietly working on some improved documentation. Let me know what you think. Keep in mind this is really just in the concept phase, and I'm not even sure yet if it's something we want. If we like it, we can continue with improvements.
http://justanotherlanguage.org/quickref You may also download the .CHM (windows help file) for local use. I suggest you *use the Index tab*. http://justanotherlanguage.org/sites/default/files/ftp_server/jallib_files/jal_quickref.chm It's a quick reference doc for Jalv2 syntax, Jallib Libraries, Jallib procedures and functions. If we decide we like it, and want to keep it, we can improve it by deciding on a standard format for Jallib procedure & function descriptions. Rob and I have come up with this standard format to use in our Jallib libraries as comments before each routine. I am not suggesting we make this a requirement for our libraries, but an *optional* way to describe each routine that can be easily ingested into this quickref doc. -------------------------------------------------------------------------------- -- Description: Verify CRC16 result -- - this may be a long description, continue on this line -- Parameters: -- - data - array of bytes to process -- - length - number of bytes -- Returns: -- - TRUE - if CRC values match -- - FALSE - if CRC value does not match -- Notes: some notes can go here for this procedure, I'm describing -- - them here. -------------------------------------------------------------------------------- I've update the sd_card.jal library to use the above format. Libraries that do not use this format may not show correctly in this quickref doc, although I was able to pull most existing function & procedure comments. To have a good feel for what's in the quickref doc, try the following searches: *_usec_delay* - Shows how to use this JALv2 syntax. *sd_card* - brings up doc for the sd_card library, shows global variables and constants *sd_print_error* - shows the procedure and description, and parameter comments (pulled from the standard comment block above) and a sample that uses the procedure (highlighted where used). Jallib routines starting with underscore "_" are internal to the library (not for the user), and therefore are not in the quickref doc. Many improvements need to be made. Please make suggestions. These are things I already know are an issue: - need to improve JALv2 syntax pages - Use of upper case/lower case should match the jallib style guide - Some procedures/functions don't show a proper description or may be a mess. To improve with the standard format description block above. - Some formatting issues. - Website needs improvements, or to be made wide enough. I do realize we already have doc in https://github.com/jallib/jallib/tree/master/doc/html, does anyone use it? Thanks, Matt. -- You received this message because you are subscribed to the Google Groups "jallib" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion visit https://groups.google.com/d/msgid/jallib/0cd2a4b4-fbde-43fa-ab5f-839cec0f0571n%40googlegroups.com.
