Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
I'm hoping to pick up Issue 295 from Google's Code-Prettify project; i.e. to add support for lang-powershell.
Whilst I've found some code examples, I can't find any documentation on how this code should be written, or any submission guidelines (e.g. should syntax highlighting work for invalid code, or should it attempt to highlight such errors)?
Ironically I've tried Googling, but with no joy. The best I could find was their Style Guide.
Question
Please could someone point me to documentation for submitting a new language support script to Google Code Prettify?
should syntax highlighting work for invalid code
or should it attempt to highlight such errors
Prettify is often applied to code fragments, so you can assume that the fragment starts at a token boundary, but should not assume that it starts at a top level production.
On sites like SO, prettify is applied to inputs written by novices and maintainers who have a passing familiarity with other languages and are trying to make spot edits to an existing snippet of code.
Prettify should make it easy for people with a deep understanding of the language to quickly scan for problems in the snippet of code.
You should make a best effort to recover from errors. For example, if the snippet only includes single-line tokens, then an invalid token on one line shouldn't prevent prettifying of every subsequent line. If that's unavoidable, then an invalid token shouldn't prevent prettifying of previous tokens -- seeing where tokenizing fails can convey useful information to someone scanning a code snippet for problems.
If you want to call out obvious errors like unclosed string literals, that's great. I'd apply .err and then a style that wants to apply a wiggly underline in red could do so. I'd be happy to accept a change to the default stylesheet for that.
The way I think about it is that prettify bridges the gap between two concepts of language:
In parser theory, a "language" is a set of strings. The PowerShell language is the set of strings defined by a grammar in a spec document.
In common descriptivist usage, a "language" relates that which is produced by a speaker or author in the associated linguistic community to that which is in their mind when they produce the string. When a programmer sits down to produce a PowerShell script, what they produce is a string in the language even if they do a bad job or their mental model of PowerShell differs significantly from the spec document.
In the first sense, there is no such thing as a malformed PowerShell program, just a string that is not in the language and hence has no semantics per the spec. In the second, a malformed PowerShell program is a PowerShell program.
Please keep the second definition in mind, and remember that prettify does not need to work on the output of code generators.
Related
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 5 years ago.
Improve this question
The structure of a FiM++ program requires that it end with the closing of a letter and the code author's name in a specific manner.
Dear Princess Celestia and Stack Exchange and String: A Sample:
...
Your faithful student, Southpaw Hare!
According to the language specification, the keyword "Your faithful student," (including the comma but not the following space) is used as an end tag for class definitions, and the following name is a comment with no syntactical effect.
The fact that the author is automatically included (if not strictly required) in every file makes me wonder if it can be used as a form of interpretable documentation akin to Java Docs. In other words, that other programs or editors would be able to parse out this name and use it in some manner.
What is the requirement of such internal comment-based documentation? Is there anything in this particular type of syntax that would cause problems?
Is the keyword sufficient to fit with the theme? It occurs to me that the lack of ability to use "Your faithful students," for a plural form (or possibly "Yours faithful," or "Yours truly," for an ambiguous version) would make listing multiple authors look awkward and unnatural (and looking like a natural human-written letter is one of the core design paradigms).
If creating a Java Docs methodology was considered, then what other features should be included? For one, a date seems common. Including some form of date comment at the top of the letter would probably look natural and not defy the design paradigm.
Since the language is new, unfamiliar to most, and honestly quite silly, here are a few resources to consider:
Original Release Announcement
October Followup
Sorry no one's given this any concern before me!
I'm heading development of the language, so I think I have a good grasp on the answer, here.
What is the requirement of such internal comment-based
documentation? Is there anything in this particular type
of syntax that would cause problems?
I've never considered an auto documentation technique like Javadoc, so there is no formal syntax for that. The compiler I'm working on completely discards comments, so it won't support it, but I'm sure it wouldn't be terribly hard.
Is the keyword sufficient to fit with the theme? It occurs to me
that the lack of ability to use "Your faithful students," for a
plural form (or possibly "Yours faithful," or "Yours truly," for an
ambiguous version) would make listing multiple authors look awkward
and unnatural (and looking like a natural pony-written letter is one
of the core design paradigms).
The idea of the author name on the last line was intended for the foremost author of the report, so multiple authors was never suggested before now. However, Your faithful students, would work nicely!
If creating a Java Docs methodology was considered, then what other
features should be included? For one, a date seems common. Including
some form of date comment at the top of the letter would probably
look natural and not defy the design paradigm.
Indeed! Perhaps something at the bottom of the report, like
(Written 2013-04-11)
Hope this help you. You have some great ideas, here, too! You should join the team!
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
I'm looking into writing documentation about some functions but do not want to write the documentation in the source code.
Is there a template I can follow, e.g XML, or something which can generate some sort of Javadoc-ish looking style documentation?
There's docbook, but to be fair, docbook excels at book or manual style documentation. It does do website documentation, but its websites tend to not be as heavily interlinked as javadoc. This is an example of a docbook document rendered to a website.
Docbook excels when you have one "source document" that doesn't have a presentation in the real world, and a few "rendered documents" that all must contain correct, up to date information built from the source document.
It is hard to understand what you are looking for, mainly because it seems that you are not exactly sure yourself. Javadoc is documentation that was purpose designed to document Java code, so a "javadoc like documentation without source code" is a hard idea to follow. Perhaps if you sat down and thought about the main sections of documentation, you'd find an outline (which might heavily include the navigation you want to use). Then it would be much easier to fill in the blanks, because you have blanks.
You can use the javadoc engine to generate documentation. It is very configurable; and supports two kinds of plugins. One to add additional "tags" and one to add / override additional "layouts". However, these tags and layouts operate on an API that tends to be Java source code oriented, such that a "javadoc comment before a class" calls a method that effectively handles the javadoc for this class. As such, without Java source code (or something very like it) you have the wrong underlying API (unless you can bend it to your needs).
Maybe you are looking for something like Doxygen, an API-documentation tool that can also be used to write other documents (f.ex. the manual of doxygen was produced with Doxygen itself without normal source code.)
Another tool would be Sphinx, which can also be used for API-documentation and also manuals without source code (ex: Python documentation).
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
I'm the author of a fairly sized (and growing) framework. It primarily exposes JavaScript APIs, but also has public APIs in Ruby and a growing CoffeeScript segment. (CoffeeScript will eventually encompass most of the project, but there will always be a significant pure-JavaScript presence.)
Up until now, I've been documenting the JavaScript with PDoc and the Ruby with RDoc. Though I've no issues with RDoc, unfortunately PDoc is aging, high-maintenance, and requires a heck of a lot of typing that feels like superfluous clutter. Also, the transition of most of the code to CoffeeScript renders PDoc much less useful than it was.
Example of the project's current documentation
I've experimented with Rocco in a local branch and it works better than I expected. What's really nice is that it works with all my code, from Ruby to Coffee to JS. It's nice to see all the documentation in one place. It's kind of cool to see the source code next to the documentation, too, and this makes it very clear what a particular code segment is actually doing.
However, I am a bit worried about the overall structure. Docco/Rocco seems great for niche projects with very few public APIs, but its read-the-entire-project style strikes me as a double-edged sword. Though it's very informative, having to vertically scroll through the files without even a table of contents (not to mention, knowing which file to go to in the first place!) seems like it would make it difficult to actually find anything. Also, the default template required some hacking because the list of files was too long to be displayed. Not a huge deal but an annoyance, and a hint that this project may be out of Rocco's league.
I'm now considering CoffeeDoc. Judging just by the example, it seems promising, but it is of course Coffee-centric, which brings me back to running 3 separate documentation tools: RDoc, CoffeeDoc and -- what? JSDoc?
I'm not completely adverse to running separate tools for the separate sources, but it becomes hard to reconcile that into a coherent result that doesn't feel like 3 separate Web sites.
So I guess my question is: what tool do you use or suggest? What language(s) does it support? Is it easy to browse, read, and actually find a needle in the haystack that is your project? I'm even considering rolling my own tool at this point, except that I can't believe no one else has encountered a problem like this (and I don't really want to waste time if I don't have to).
Sphinx directly supports javascript. Documentation of Ruby and CoffeeScript is supported through extensions (https://bitbucket.org/birkenfeld/sphinx-contrib/).
From the website:
The following features are present, work fine and can be seen “in action” in the Python docs:
Output formats: HTML (including Windows HTML Help), LaTeX (for printable PDF versions), manual pages, plain text
Extensive cross-references: semantic markup and automatic links for functions, classes, citations, glossary terms and similar pieces of information
Hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents and children
Automatic indices: general index as well as a module index
Code handling: automatic highlighting using the Pygments highlighter
Extensions: automatic testing of code snippets, inclusion of docstrings from Python modules (API docs), and more
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 3 years ago.
Improve this question
I'm hoping to show a visualization of the code base which can show areas that are overly complex and intertwined.
I know what clang is, but I'm not sure it gives me what I want in this case.
AnalysisTool: I know it's a clang wrapper but it also provides dependency diagrams.
AnalysisTool was originally created to serve two main purposes: to provide an easy-to-use executable binary of Clang static analyzer and to customize Clang by providing some additional checks. When Clang static analyzer was in its early stages, the only option for developers to try it out was to check out the latest source code of LLVM and Clang, compile it, and use the analyzer from the command line. AnalysisTool provided an easy-to-use GUI interface and removed the need to touch Clang source code. It also provided automatic updates, so that users of AT could always use the latest Clang static analyzer.
lizard:
This tool will calculate the cycolomatic complexity of C/C++/Objective C code without caring about header files and preprocessors. So the tool is actually calculating how complex the code 'looks' rather than how complex the code 'is'.
People will need this tool because it's often very hard to get all the
include folders and files right with a similar tool, but we don't
really need that kind of accuracy when come to cyclomatic complexity.
These are the only two tools I know, hope this helps.
Our Source Code Search Engine provides the ability to search across large sets of source code in multiple languages, using the code structure of each language to guide the search and minimize false positive matches.
As a side effect of its indexing process, it computes various complexity metrics (Halstead, McCabe) for files and writes that to an XML file you can process/display any way you like.
It has language front ends for C and C++; either of them ought to be able to process Objective C well enough for the SCSE to operator, and for OP's purpose, to compute such complexity metrics.
The downloadable version has the C front end included.
Edit June 2019: It has an Objective C front end now.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 7 years ago.
Improve this question
I just wanted to know if you know of some projects that can help to decide whether the analyzed Source it is good code or bad RPG code.
I'm thinking on the terms of Software metric, McCabe Cyclomatic Number and all those things.
I know that those numbers are mere a hunch or two, but if you can present your management a point score they are happy and i get to modernize all those programs that otherwise work as specified but are painful to maintain.
so yeah .. know any code analyzers for (ILE)RPG ?
We have developed a tool called SourceMeter that can analyze source code conforming to RPG III and RPG IV versions (including free-form as well). It provides you the McCabe Cyclomatic Number and many other source code metrics that you can use to rate your RPG code.
If the issue is that the programs are painful to maintain, then the metric should reflect how how much pain is involved with maintaining them, such as "time to implement new feature X" vs "estimated time if codebase wasn't a steaming POS".
However, those are subjective (and always will be). IMO you're probably better off refactoring mercilessly to remove pain points from your development. You may want to look at the techniques of strangler applications to bring in a more modern platform to deliver new features without resorting to a Big Bang rewrite.
The SD Source Code Search Engine (SCSE) is a tool for rapidly search very large set of source code, using the langauge structure of each file to index the file according to code elements (identifiers, operators, constants, string literals, comments). The SD Source code engine is usable with a wide variety of langauges such as C, C++, C#, Java ... and there's a draft version of RPG.
To the OP's original question, the SCSE engine happens to compute various metrics over files as it indexes them, including SLOC, Comments, blank lines, and Halstead and Cyclomatic Complexity measures. The metrics are made available as byprooduct of the indexing step. Thus, various metrics for RPG could be obtained.
I've never seen one, although I wrote a primitive analyser for RPG400. With the advent of free form and subprocedures, it was too time consuming to modify. I wish there was an API that let me have access to the compiler lexical tables.
If you wanted to try it yourself, consider the notion of reading the bottom of the compiler listing and using the line numbers to at least get an idea of how long a variable lives. For instance, a global variable is 'worse' than a local variable. That can only be a guess because of GOTO and EXSR.
Lot of work.