salesforcefoundation / apexdoc Goto Github PK
View Code? Open in Web Editor NEWThe latest java source for ApexDoc, a tool to document your Salesforce Apex classes.
License: BSD 3-Clause "New" or "Revised" License
The latest java source for ApexDoc, a tool to document your Salesforce Apex classes.
License: BSD 3-Clause "New" or "Revised" License
I just found this project https://gitlab.com/StevenWCox/sfapexdoc/wikis/Home that also started with Aslam Bari's ApexDoc, and added a bunch of enhancements. Might be worth reviewing for ideas or code sharing.
looks like the ApexDoc parsing doesn't handle <'s >'s on return values and parameters. I did do a fix to get them handled on class names, so I need to see what was added, and add it to additional code.
I haven't seen any instructions on how this project is built but judging by the lack of either a pom.xml or a build.xml file, I would hazard that it is done by hand. This process can be enhanced by using a system like Apache Maven. This would make cutting a new release simple and repeatable.
This took me a bit to figure out why the first word of the description kept showing up with the parameter name styling but it seems like ApexDoc is looking for the first space, not just white space. Since I and many I work with like to separate the name and description with a tab, it would be helpful to split on any white space character.
if we parse @istest before the method, treat it like it has testMethod on it.
I'm not sure if this is intended or not, but HTML tags will pass through for only the brief description of a method, but not for the full method description. To be more specific...
In the method htmlForClassModel()
in FileManager.java
, when generating the HTML for <div class="methodTOCDescription">
, escapeHTML()
is NOT called, but when generating the HTML for <div class="methodDescription">
, escapeHTML()
IS called.
I understand this is a bit tricky because you want to be able to support < and > being shown in the documentation and not embedded as html tags, but it's a bit confusing that it will pass tags through for one part and escape them in another.
As for the passthrough, perhaps escapeHTML()
in FileManager.java
could be overloaded to accept an array of whitelisted ignore-tags which you know won't mess up the structure of the generated doc. Then, depending on what part of the doc you are generating when you call escapeHTML()
you can toss in different acceptable tags like <code>, <ul>, <ol>, <li>, <pre>, <p>
and maybe <b>, <i>
.
we decided that the expand/collapse ui on the pages is non-standard and not useful. we've decided to make ApexDoc more similar to Salesforce Apex documentation.
Tag could be used in comments at class level for display controllers, to display an image of an associated page.
Add another level to navigation menu, to divide into classes and object customizations (and optionally triggers). Use metadata API to retrieve information about object customizations, including comments, and produce object customizations and custom objects report on separate html page.
Executing the program breaks with NullPointerException
in ClassModel#compare
. Paths given are relative to apexdoc.jar
, which is in my project root (also tried absolute paths). The two html paths given in the parameters do exist.
The same error occurs when providing only the -s
and -t
flags (and only the -s
flag), except that it shows nine lines of Error: null
instead of two.
System: OS X El Capitan 10.11.3
$ java -version
java version "1.8.0_31"
Java(TM) SE Runtime Environment (build 1.8.0_31-b13)
Java HotSpot(TM) 64-Bit Server VM (build 25.31-b07, mixed mode)
$ java -jar apexdoc.jar -s ./src/classes \
-t ./docs \
-p 'global;public;private;testmethod;webService' \
-g https://example.com/repo/src/classes \
-h ./homepage.html \
-a ./projectheader.html
Error: null
Error: null
java.lang.NullPointerException
at org.salesforce.apexdoc.ClassModel$1.compare(ClassModel.java:55)
at org.salesforce.apexdoc.ClassModel$1.compare(ClassModel.java:1)
at java.util.TimSort.binarySort(TimSort.java:292)
at java.util.TimSort.sort(TimSort.java:217)
at java.util.Arrays.sort(Arrays.java:1512)
at java.util.ArrayList.sort(ArrayList.java:1454)
at java.util.Collections.sort(Collections.java:175)
at org.salesforce.apexdoc.ClassModel.getMethodsSorted(ClassModel.java:48)
at org.salesforce.apexdoc.FileManager.htmlForClassModel(FileManager.java:217)
at org.salesforce.apexdoc.FileManager.makeFile(FileManager.java:143)
at org.salesforce.apexdoc.FileManager.createDoc(FileManager.java:429)
at org.salesforce.apexdoc.ApexDoc.RunApexDoc(ApexDoc.java:128)
at org.salesforce.apexdoc.ApexDoc.main(ApexDoc.java:36)
null
ApexDoc - a tool for generating documentation from Salesforce Apex code class files.
Invalid Arguments detected. The correct syntax is:
apexdoc -s <source_directory> [-t <target_directory>] [-g <source_url>] [-h <homefile>] [-a <authorfile>] [-p <scope>]
<source_directory> - The folder location which contains your apex .cls classes
<target_directory> - Optional. Specifies your target folder where documentation will be generated.
<source_url> - Optional. Specifies a URL where the source is hosted (so ApexDoc can provide links to your source).
<homefile> - Optional. Specifies the html file that contains the contents for the home page's content area.
<authorfile> - Optional. Specifies the text file that contains project information for the documentation header.
<scope> - Optional. Semicolon seperated list of scopes to document. Defaults to 'global;public'.
This is an example from the Apex Doc version:
ApexDoc can end up hiding methods that are overloaded, only showing the last one. If you are using these docs to communicate your api, then this is a pretty big loss.
I was getting an invalid argument error. I narrowed it down to a single if statement in one of my files.
An error shows up when this statement has spaces between c.commentPublic and !=
This works: if(c.commentPublic!=null){
This does not work: if(c.commentPublic !=null){
Version 1.1.5
Error log
java.lang.NullPointerException
at org.salesforce.apexdoc.ClassModel$1.compare(ClassModel.java:55)
at org.salesforce.apexdoc.ClassModel$1.compare(ClassModel.java:1)
at java.util.TimSort.countRunAndMakeAscending(TimSort.java:360)
at java.util.TimSort.sort(TimSort.java:220)
at java.util.Arrays.sort(Arrays.java:1512)
at java.util.ArrayList.sort(ArrayList.java:1454)
at java.util.Collections.sort(Collections.java:175)
at org.salesforce.apexdoc.ClassModel.getMethodsSorted(ClassModel.java:48)
at org.salesforce.apexdoc.FileManager.htmlForClassModel(FileManager.java:217)
at org.salesforce.apexdoc.FileManager.makeFile(FileManager.java:143)
at org.salesforce.apexdoc.FileManager.createDoc(FileManager.java:429)
at org.salesforce.apexdoc.ApexDoc.RunApexDoc(ApexDoc.java:128)
at org.salesforce.apexdoc.ApexDoc.main(ApexDoc.java:36)
Want to make sure we credit him for the original version, obviously this is quite a bit more evolved ;)
http://techsahre.blogspot.com/2011/01/apexdoc-salesforce-code-documentation.html
ApexDoc currently works in the Class directory you specify and it is looking for .cls files.
It'd be nice to have an index similar to
http://docs.oracle.com/javase/7/docs/api/index-files/index-1.html
Currently, ApexDoc will include in the documentation set all classes, methods, and properties that are of the specified scope(s).
Some users may prefer to only have it generate documentation for classes, methods, and properties that have a comment block.
It would be nice to provide an option (command line flag, and PlugIn checkbox) to control this behavior.
Feb 6, 2013 Delete comment #1 [email protected]
The skip-undocumented option is useful when documenting the global classes in a managed package, and there are some utility classes that are not included in the package.
should they be in a separate section?
This is typically what I see done in javadocs.
currently, when you click on the class group name, it shows the list of classes in the group, and displays the class group content file. but if you click on the class group name again, it just refreshes to the same state. it would be preferable if it would collapse its group, but still stay on its content file. this would make ease of use better.
ApexDoc should know what invocableMethods are, grab their description and label, and perhaps show the invocableVariables with descriptions
Right now, html for the pages is constructed using string concatenation. Not only can this be expensive but it makes handling issues and enhancements on the page more difficult than it needs to be. I propose using a templating engine to separate the html from the logic.
currently, they appear in the order they exist in the class file. would Alpha be better?
Getting error as
Invalid Arguments detected.
i am running below command from command prompt
java -jar apexdoc.jar -s 'C:\workspace\SalesForce\src\classes' -t 'C:\Desktop\Purpose Documents'
The readme mentions the option -a banner_page
, but that seems to not actually exist.
currently, changing the filter scope hides classes in the menu, but the class groups always remain. Ideally, if a class group would have no classes in the current scope, we should hide the class group.
Add another level to main navigation menu to separate classes, triggers (optionally object customizations and custom objects). Add a runtime switch to locate triggers. Add parsing code to determine trigger firing conditions.
Is there an example of working home content and banner pages? It seems to ignore them, whether the content is bounded by <html></html> or not.
Right now, there are a few spots were the old Google Code project hosting is referenced. These should be updated to point to the GitHub repo.
we agreed to remove expand/collapse, but to provide the list of methods, much like Salesforce Apex documentation has.
With the complex parsing taking place, I feel that there would be a real benefit to adding unit tests. This would help reassure a developer (especially one just getting started with the code) that a change will not break anything. Tests are never a 100% guarantee but it is way better than nothing.
allow the user to turn on/off all of the scopes they built the docset with, including global, public, private, testMethod, webService.
Apex code that is an interface, not a class, is currently ignored.
If I create a class with multiple constructors then only one constructor is displayed in ApexDoc.
For example, ApexDoc produced using below code includes only the second constructor (one with a parameter) in the documentation.
global class ProgramService {
/*******************************************************************************************************
}
Doesn't work when dropped into plugins or dropins directory, doesn't work when Eclipse run as admin, doesn't work when source downloaded and plug-in development installed. No context menu under any conditions.
If you have a class defined within another class, its definition is ignored, and any methods and properties of the nested class are documented along with the documentation for the outer class.
kbromer-ltm:Workspace kbromer$ java -jar apexdoc.jar
-s '/Users/kbromer/Workspace/Cumulus/src/classes'
-t '/Users/kbromer/Workspace/Cumulus_Apexdoc_Test'
-g 'http://github.com/SalesforceFoundation/Cumulus/blob/dev/src/classes/'
java.lang.ArrayIndexOutOfBoundsException: 3
at org.salesforce.apexdoc.ApexDoc.RunApexDoc(ApexDoc.java:87)
at org.salesforce.apexdoc.ApexDoc.main(ApexDoc.java:34)
Works fine if I include the optional param
ApexDoc was requiring slash star star, but that meant it mistakenly parsed keywords (class, public, global, etc.) in a normal comment. I changed the parser to handle just slash star, and that resolved the incorrect parsing. Any problems with this?
It would be nice if any comment block before a method or property that has no tags, would treat the comment text as if it was for the @description. this would then cause many methods to get somewhat documented even if the user wasn't using full ApexDoc tag formatting.
SfApexDoc does this.
currently, one must expand the method list to see the full method signature. It would be nice if in the collapsed state, the method name bars had some sort of visual to indicate scope.
we could potentially do something similar in the class menu. I currently am just using color of the class (blue = global, black = public, gray = private).
the listing of groups and classes in the menu should display them in alphabetical order. currently looks random!!
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.