Using Documentation Links with Sensei
One of the difficulties with learning a new library, or sharing agreed practices across our team is documenting and creating examples.
Very often we create small example projects, but we don't have them open when working with actual code.
I've often thought it would be great to have the ability to link to our examples, or online examples and be able to go to a URL for more explanation when needed.
With Java, we have JavaDoc comments, which can have a see annotation:
/**
* @see <a href="https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations">Junit 5 Annotation docs</a>
*/
JavaDoc like this in 3rd party libraries is a great help because we can use the Quick Documentation functionality in IntelliJ to have access to more detailed examples.
But, we all know that comments don't get updated as often as code, and web presence maintenance is often disconnected from library maintenance and sometimes performed by a different team entirely.
How Sensei Helps
Sensei provides the ability to match on library annotations and methods to provide links to long form documentation on a wiki or third party tutorial site.
As an example, I'm using the @Test annotation from JUnit.
The JavaDoc is very detailed, and the Quick Documentation view explains how to use the annotation.
But the official documentation on the web site is often easier to read and has more examples.
When a team starts learning a library, having a set of recommended tutorials, can be very useful.
Sensei has a goto action that we can use to open a URL, allowing us to link to external sites and examples for documentation that we, as a team, find useful.
Implementing the Goto URL
To implement this I would create a search that matches the @Test annotation from Junit.
search:
annotation:
owner:
method: {}
type: "org.junit.jupiter.api.Test"
And then I would add goto actions for each of the URLs I find useful.
e.g.
- https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations
- https://junit.org/junit5/docs/current/user-guide/#writing-tests-classes-and-methods
The example below would create a single Action JUnit Annotations (learn) which would open both URLs in a browser at the same time.
availableFixes:
- name: "Learn about JUnit Annotations"
actions:
- goto:
type: "URL"
value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations"=
- goto:
type: "URL"
value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-classes-and-methods"
And when I activate it in IntelliJ with Alt+Enter I see the context menu which I can select to jump to the documentation.
Multiple Actions
I might choose to have multiple Actions so that each URL or tutorial has its own option in the alt+enter Quick Fix pop up menu.
For example, for the @Parameterized annotation, I might want to link to the official documentation and a set of online example code.
- https://junit.org/junit5/docs/current/user-guide/#writing-tests-parameterized-tests
- https://github.com/eviltester/junitexamples/blob/master/src/test/java/parameterized/junit5/InitialExampleTest.java
I would simply create a recipe that searches for the annotation:
search:
annotation:
owner:
method: {}
type: "org.junit.jupiter.params.ParameterizedTest"
And links off to the sites I identified as being useful:
availableFixes:
- name: "JUnit Annotations (learn)"
actions:
- goto:
type: "URL"
value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations"
- name: "What is a JUnit Test? (learn)"
actions:
- goto:
type: "URL"
value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-classes-and-methods"
Both links would then appear in the pop-up dialog.
Who would benefit?
I would have found this useful when using and learning libraries, especially when leading teams and helping them adopt a new library.
This could also benefit teams creating libraries, by creating a standard set of documentation recipes to help guide people through the adoption of the library or new features in the library.
This would be especially useful if the code maintenance and documentation maintenance are performed by different teams.
You can install Sensei from within IntelliJ using `preferences > plugins` (just search for "sensei secure code").
All the code for this blog post is on Github in the junitexamples module in https://github.com/SecureCodeWarrior/sensei-blog-examples
Alan Richardson has more than twenty years of professional IT experience, working as a developer and at every level of the testing hierarchy from Tester through to Head of Testing. Head of Developer Relations at Secure Code Warrior, he works directly with teams, to improve the development of quality secure code. Alan is the author of four books including “Dear Evil Tester”, and “Java For Testers”. Alan has also created online training courses to help people learn Technical Web Testing and Selenium WebDriver with Java. Alan posts his writing and training videos on SeleniumSimplified.com, EvilTester.com, JavaForTesters.com, and CompendiumDev.co.uk.
Secure Code Warrior is here for your organization to help you secure code across the entire software development lifecycle and create a culture in which cybersecurity is top of mind. Whether you’re an AppSec Manager, Developer, CISO, or anyone involved in security, we can help your organization reduce risks associated with insecure code.
Book a demoAlan Richardson has more than twenty years of professional IT experience, working as a developer and at every level of the testing hierarchy from Tester through to Head of Testing. Head of Developer Relations at Secure Code Warrior, he works directly with teams, to improve the development of quality secure code. Alan is the author of four books including “Dear Evil Tester”, and “Java For Testers”. Alan has also created online training courses to help people learn Technical Web Testing and Selenium WebDriver with Java. Alan posts his writing and training videos on SeleniumSimplified.com, EvilTester.com, JavaForTesters.com, and CompendiumDev.co.uk.
One of the difficulties with learning a new library, or sharing agreed practices across our team is documenting and creating examples.
Very often we create small example projects, but we don't have them open when working with actual code.
I've often thought it would be great to have the ability to link to our examples, or online examples and be able to go to a URL for more explanation when needed.
With Java, we have JavaDoc comments, which can have a see annotation:
/**
* @see <a href="https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations">Junit 5 Annotation docs</a>
*/
JavaDoc like this in 3rd party libraries is a great help because we can use the Quick Documentation functionality in IntelliJ to have access to more detailed examples.
But, we all know that comments don't get updated as often as code, and web presence maintenance is often disconnected from library maintenance and sometimes performed by a different team entirely.
How Sensei Helps
Sensei provides the ability to match on library annotations and methods to provide links to long form documentation on a wiki or third party tutorial site.
As an example, I'm using the @Test annotation from JUnit.
The JavaDoc is very detailed, and the Quick Documentation view explains how to use the annotation.
But the official documentation on the web site is often easier to read and has more examples.
When a team starts learning a library, having a set of recommended tutorials, can be very useful.
Sensei has a goto action that we can use to open a URL, allowing us to link to external sites and examples for documentation that we, as a team, find useful.
Implementing the Goto URL
To implement this I would create a search that matches the @Test annotation from Junit.
search:
annotation:
owner:
method: {}
type: "org.junit.jupiter.api.Test"
And then I would add goto actions for each of the URLs I find useful.
e.g.
- https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations
- https://junit.org/junit5/docs/current/user-guide/#writing-tests-classes-and-methods
The example below would create a single Action JUnit Annotations (learn) which would open both URLs in a browser at the same time.
availableFixes:
- name: "Learn about JUnit Annotations"
actions:
- goto:
type: "URL"
value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations"=
- goto:
type: "URL"
value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-classes-and-methods"
And when I activate it in IntelliJ with Alt+Enter I see the context menu which I can select to jump to the documentation.
Multiple Actions
I might choose to have multiple Actions so that each URL or tutorial has its own option in the alt+enter Quick Fix pop up menu.
For example, for the @Parameterized annotation, I might want to link to the official documentation and a set of online example code.
- https://junit.org/junit5/docs/current/user-guide/#writing-tests-parameterized-tests
- https://github.com/eviltester/junitexamples/blob/master/src/test/java/parameterized/junit5/InitialExampleTest.java
I would simply create a recipe that searches for the annotation:
search:
annotation:
owner:
method: {}
type: "org.junit.jupiter.params.ParameterizedTest"
And links off to the sites I identified as being useful:
availableFixes:
- name: "JUnit Annotations (learn)"
actions:
- goto:
type: "URL"
value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations"
- name: "What is a JUnit Test? (learn)"
actions:
- goto:
type: "URL"
value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-classes-and-methods"
Both links would then appear in the pop-up dialog.
Who would benefit?
I would have found this useful when using and learning libraries, especially when leading teams and helping them adopt a new library.
This could also benefit teams creating libraries, by creating a standard set of documentation recipes to help guide people through the adoption of the library or new features in the library.
This would be especially useful if the code maintenance and documentation maintenance are performed by different teams.
You can install Sensei from within IntelliJ using `preferences > plugins` (just search for "sensei secure code").
All the code for this blog post is on Github in the junitexamples module in https://github.com/SecureCodeWarrior/sensei-blog-examples
One of the difficulties with learning a new library, or sharing agreed practices across our team is documenting and creating examples.
Very often we create small example projects, but we don't have them open when working with actual code.
I've often thought it would be great to have the ability to link to our examples, or online examples and be able to go to a URL for more explanation when needed.
With Java, we have JavaDoc comments, which can have a see annotation:
/**
* @see <a href="https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations">Junit 5 Annotation docs</a>
*/
JavaDoc like this in 3rd party libraries is a great help because we can use the Quick Documentation functionality in IntelliJ to have access to more detailed examples.
But, we all know that comments don't get updated as often as code, and web presence maintenance is often disconnected from library maintenance and sometimes performed by a different team entirely.
How Sensei Helps
Sensei provides the ability to match on library annotations and methods to provide links to long form documentation on a wiki or third party tutorial site.
As an example, I'm using the @Test annotation from JUnit.
The JavaDoc is very detailed, and the Quick Documentation view explains how to use the annotation.
But the official documentation on the web site is often easier to read and has more examples.
When a team starts learning a library, having a set of recommended tutorials, can be very useful.
Sensei has a goto action that we can use to open a URL, allowing us to link to external sites and examples for documentation that we, as a team, find useful.
Implementing the Goto URL
To implement this I would create a search that matches the @Test annotation from Junit.
search:
annotation:
owner:
method: {}
type: "org.junit.jupiter.api.Test"
And then I would add goto actions for each of the URLs I find useful.
e.g.
- https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations
- https://junit.org/junit5/docs/current/user-guide/#writing-tests-classes-and-methods
The example below would create a single Action JUnit Annotations (learn) which would open both URLs in a browser at the same time.
availableFixes:
- name: "Learn about JUnit Annotations"
actions:
- goto:
type: "URL"
value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations"=
- goto:
type: "URL"
value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-classes-and-methods"
And when I activate it in IntelliJ with Alt+Enter I see the context menu which I can select to jump to the documentation.
Multiple Actions
I might choose to have multiple Actions so that each URL or tutorial has its own option in the alt+enter Quick Fix pop up menu.
For example, for the @Parameterized annotation, I might want to link to the official documentation and a set of online example code.
- https://junit.org/junit5/docs/current/user-guide/#writing-tests-parameterized-tests
- https://github.com/eviltester/junitexamples/blob/master/src/test/java/parameterized/junit5/InitialExampleTest.java
I would simply create a recipe that searches for the annotation:
search:
annotation:
owner:
method: {}
type: "org.junit.jupiter.params.ParameterizedTest"
And links off to the sites I identified as being useful:
availableFixes:
- name: "JUnit Annotations (learn)"
actions:
- goto:
type: "URL"
value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations"
- name: "What is a JUnit Test? (learn)"
actions:
- goto:
type: "URL"
value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-classes-and-methods"
Both links would then appear in the pop-up dialog.
Who would benefit?
I would have found this useful when using and learning libraries, especially when leading teams and helping them adopt a new library.
This could also benefit teams creating libraries, by creating a standard set of documentation recipes to help guide people through the adoption of the library or new features in the library.
This would be especially useful if the code maintenance and documentation maintenance are performed by different teams.
You can install Sensei from within IntelliJ using `preferences > plugins` (just search for "sensei secure code").
All the code for this blog post is on Github in the junitexamples module in https://github.com/SecureCodeWarrior/sensei-blog-examples
Click on the link below and download the PDF of this resource.
Secure Code Warrior is here for your organization to help you secure code across the entire software development lifecycle and create a culture in which cybersecurity is top of mind. Whether you’re an AppSec Manager, Developer, CISO, or anyone involved in security, we can help your organization reduce risks associated with insecure code.
View reportBook a demoAlan Richardson has more than twenty years of professional IT experience, working as a developer and at every level of the testing hierarchy from Tester through to Head of Testing. Head of Developer Relations at Secure Code Warrior, he works directly with teams, to improve the development of quality secure code. Alan is the author of four books including “Dear Evil Tester”, and “Java For Testers”. Alan has also created online training courses to help people learn Technical Web Testing and Selenium WebDriver with Java. Alan posts his writing and training videos on SeleniumSimplified.com, EvilTester.com, JavaForTesters.com, and CompendiumDev.co.uk.
One of the difficulties with learning a new library, or sharing agreed practices across our team is documenting and creating examples.
Very often we create small example projects, but we don't have them open when working with actual code.
I've often thought it would be great to have the ability to link to our examples, or online examples and be able to go to a URL for more explanation when needed.
With Java, we have JavaDoc comments, which can have a see annotation:
/**
* @see <a href="https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations">Junit 5 Annotation docs</a>
*/
JavaDoc like this in 3rd party libraries is a great help because we can use the Quick Documentation functionality in IntelliJ to have access to more detailed examples.
But, we all know that comments don't get updated as often as code, and web presence maintenance is often disconnected from library maintenance and sometimes performed by a different team entirely.
How Sensei Helps
Sensei provides the ability to match on library annotations and methods to provide links to long form documentation on a wiki or third party tutorial site.
As an example, I'm using the @Test annotation from JUnit.
The JavaDoc is very detailed, and the Quick Documentation view explains how to use the annotation.
But the official documentation on the web site is often easier to read and has more examples.
When a team starts learning a library, having a set of recommended tutorials, can be very useful.
Sensei has a goto action that we can use to open a URL, allowing us to link to external sites and examples for documentation that we, as a team, find useful.
Implementing the Goto URL
To implement this I would create a search that matches the @Test annotation from Junit.
search:
annotation:
owner:
method: {}
type: "org.junit.jupiter.api.Test"
And then I would add goto actions for each of the URLs I find useful.
e.g.
- https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations
- https://junit.org/junit5/docs/current/user-guide/#writing-tests-classes-and-methods
The example below would create a single Action JUnit Annotations (learn) which would open both URLs in a browser at the same time.
availableFixes:
- name: "Learn about JUnit Annotations"
actions:
- goto:
type: "URL"
value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations"=
- goto:
type: "URL"
value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-classes-and-methods"
And when I activate it in IntelliJ with Alt+Enter I see the context menu which I can select to jump to the documentation.
Multiple Actions
I might choose to have multiple Actions so that each URL or tutorial has its own option in the alt+enter Quick Fix pop up menu.
For example, for the @Parameterized annotation, I might want to link to the official documentation and a set of online example code.
- https://junit.org/junit5/docs/current/user-guide/#writing-tests-parameterized-tests
- https://github.com/eviltester/junitexamples/blob/master/src/test/java/parameterized/junit5/InitialExampleTest.java
I would simply create a recipe that searches for the annotation:
search:
annotation:
owner:
method: {}
type: "org.junit.jupiter.params.ParameterizedTest"
And links off to the sites I identified as being useful:
availableFixes:
- name: "JUnit Annotations (learn)"
actions:
- goto:
type: "URL"
value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-annotations"
- name: "What is a JUnit Test? (learn)"
actions:
- goto:
type: "URL"
value: "https://junit.org/junit5/docs/current/user-guide/#writing-tests-classes-and-methods"
Both links would then appear in the pop-up dialog.
Who would benefit?
I would have found this useful when using and learning libraries, especially when leading teams and helping them adopt a new library.
This could also benefit teams creating libraries, by creating a standard set of documentation recipes to help guide people through the adoption of the library or new features in the library.
This would be especially useful if the code maintenance and documentation maintenance are performed by different teams.
You can install Sensei from within IntelliJ using `preferences > plugins` (just search for "sensei secure code").
All the code for this blog post is on Github in the junitexamples module in https://github.com/SecureCodeWarrior/sensei-blog-examples
Table of contents
Alan Richardson has more than twenty years of professional IT experience, working as a developer and at every level of the testing hierarchy from Tester through to Head of Testing. Head of Developer Relations at Secure Code Warrior, he works directly with teams, to improve the development of quality secure code. Alan is the author of four books including “Dear Evil Tester”, and “Java For Testers”. Alan has also created online training courses to help people learn Technical Web Testing and Selenium WebDriver with Java. Alan posts his writing and training videos on SeleniumSimplified.com, EvilTester.com, JavaForTesters.com, and CompendiumDev.co.uk.
Secure Code Warrior is here for your organization to help you secure code across the entire software development lifecycle and create a culture in which cybersecurity is top of mind. Whether you’re an AppSec Manager, Developer, CISO, or anyone involved in security, we can help your organization reduce risks associated with insecure code.
Book a demoDownloadResources to get you started
Benchmarking Security Skills: Streamlining Secure-by-Design in the Enterprise
The Secure-by-Design movement is the future of secure software development. Learn about the key elements companies need to keep in mind when they think about a Secure-by-Design initiative.
DigitalOcean Decreases Security Debt with Secure Code Warrior
DigitalOcean's use of Secure Code Warrior training has significantly reduced security debt, allowing teams to focus more on innovation and productivity. The improved security has strengthened their product quality and competitive edge. Looking ahead, the SCW Trust Score will help them further enhance security practices and continue driving innovation.
Resources to get you started
Trust Score Reveals the Value of Secure-by-Design Upskilling Initiatives
Our research has shown that secure code training works. Trust Score, using an algorithm drawing on more than 20 million learning data points from work by more than 250,000 learners at over 600 organizations, reveals its effectiveness in driving down vulnerabilities and how to make the initiative even more effective.
Reactive Versus Preventive Security: Prevention Is a Better Cure
The idea of bringing preventive security to legacy code and systems at the same time as newer applications can seem daunting, but a Secure-by-Design approach, enforced by upskilling developers, can apply security best practices to those systems. It’s the best chance many organizations have of improving their security postures.
The Benefits of Benchmarking Security Skills for Developers
The growing focus on secure code and Secure-by-Design principles requires developers to be trained in cybersecurity from the start of the SDLC, with tools like Secure Code Warrior’s Trust Score helping measure and improve their progress.
Driving Meaningful Success for Enterprise Secure-by-Design Initiatives
Our latest research paper, Benchmarking Security Skills: Streamlining Secure-by-Design in the Enterprise is the result of deep analysis of real Secure-by-Design initiatives at the enterprise level, and deriving best practice approaches based on data-driven findings.