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 10 months ago.
Improve this question
This is regaarding Google Speech to text API:
API
I want to develop Spring Boot Java Web App:
The app is launched in local host
I open browser to http://localhost:8080
The app displays simple UI, main window that display live realtime captions for
any English audio comping from the laptop speaker which could be zoom video call in which participants are speaking and I hear them and I also see the live captions in my local web app
Live captions remains on the screen in a window with scrollbar
Live captions are saved in text file as new captions keep on appending in the text file
It is critical for the captions to have best accuracy and display captions quickly as the person is speaking.
Can this be achieved? If not possible with Google API, what is the alternative API?
If I am understanding you correctly, IMHO I would separate it into two parts
Transcribe the speec to text, like below from google api
and then do the caption as stream overlay
//
// Performs streaming speech recognition on raw PCM audio data.
//
// #param fileName the path to a PCM audio file to transcribe.
//
public static void streamingRecognizeFile(String fileName) throws Exception, IOException {
Path path = Paths.get(fileName);
byte[] data = Files.readAllBytes(path);
// Instantiates a client with GOOGLE_APPLICATION_CREDENTIALS
try (SpeechClient speech = SpeechClient.create()) {
// Configure request with local raw PCM audio
RecognitionConfig recConfig =
RecognitionConfig.newBuilder()
.setEncoding(AudioEncoding.LINEAR16)
.setLanguageCode("en-US")
.setSampleRateHertz(16000)
.setModel("default")
.build();
StreamingRecognitionConfig config =
StreamingRecognitionConfig.newBuilder().setConfig(recConfig).build();
class ResponseApiStreamingObserver<T> implements ApiStreamObserver<T> {
private final SettableFuture<List<T>> future = SettableFuture.create();
private final List<T> messages = new java.util.ArrayList<T>();
#Override
public void onNext(T message) {
messages.add(message);
}
#Override
public void onError(Throwable t) {
future.setException(t);
}
#Override
public void onCompleted() {
future.set(messages);
}
// Returns the SettableFuture object to get received messages / exceptions.
public SettableFuture<List<T>> future() {
return future;
}
}
ResponseApiStreamingObserver<StreamingRecognizeResponse> responseObserver =
new ResponseApiStreamingObserver<>();
BidiStreamingCallable<StreamingRecognizeRequest, StreamingRecognizeResponse> callable =
speech.streamingRecognizeCallable();
ApiStreamObserver<StreamingRecognizeRequest> requestObserver =
callable.bidiStreamingCall(responseObserver);
// The first request must **only** contain the audio configuration:
requestObserver.onNext(
StreamingRecognizeRequest.newBuilder().setStreamingConfig(config).build());
// Subsequent requests must **only** contain the audio data.
requestObserver.onNext(
StreamingRecognizeRequest.newBuilder()
.setAudioContent(ByteString.copyFrom(data))
.build());
// Mark transmission as completed after sending the data.
requestObserver.onCompleted();
List<StreamingRecognizeResponse> responses = responseObserver.future().get();
for (StreamingRecognizeResponse response : responses) {
// For streaming recognize, the results list has one is_final result (if available) followed
// by a number of in-progress results (if iterim_results is true) for subsequent utterances.
// Just print the first result here.
StreamingRecognitionResult result = response.getResultsList().get(0);
// There can be several alternative transcripts for a given chunk of speech. Just use the
// first (most likely) one here.
SpeechRecognitionAlternative alternative = result.getAlternativesList().get(0);
System.out.printf("Transcript : %s\n", alternative.getTranscript());
}
}
}
For your mobile Voice overlay
https://github.com/algolia/voice-overlay-android
For web HTML 5 overlay
<video id="video" controls preload="metadata">
<source src="video/sintel-short.mp4" type="video/mp4">
<source src="video/sintel-short.webm" type="video/webm">
<track label="English" kind="subtitles" srclang="en" src="captions/vtt/sintel-en.vtt" default>
<track label="Deutsch" kind="subtitles" srclang="de" src="captions/vtt/sintel-de.vtt">
<track label="Español" kind="subtitles" srclang="es" src="captions/vtt/sintel-es.vtt">
</video>
// per the sample linked above you can feed the / append the captions
var subtitlesMenu;
if (video.textTracks) {
var df = document.createDocumentFragment();
var subtitlesMenu = df.appendChild(document.createElement('ul'));
subtitlesMenu.className = 'subtitles-menu';
subtitlesMenu.appendChild(createMenuItem('subtitles-off', '', 'Off'));
for (var i = 0; i < video.textTracks.length; i++) {
subtitlesMenu.appendChild(createMenuItem('subtitles-' + video.textTracks[i].language, video.textTracks[i].language, video.textTracks[i].label));
}
videoContainer.appendChild(subtitlesMenu);
}
One of the fastest and most efficient ways to convert speech to text is Java Speech API (documentation at https://www.oracle.com/java/technologies/speech-api-frequently-asked-questions.html)
In the course of text conversion, you will need to break it down to pieces and because of this, the meaning may change slightly, since some expressions may have a different meaning than a single word, but this will help reduce the time of the final translation. Then send the already received segments (words, phrases) via API for translation.
You can choose several options you like (for example https://rapidapi.com/blog/best-translation-api/) and check which one will work faster. In my experience "Microsoft Translator Text" and "Google Translate" are some of the fastest. I also think that you will not be able to get instant translation, but if you test several API options and play around with whether to process all sentences, phrases or individual words at once, you can reduce the translation time to a minimum.
I am currently trying to implement file exports in background so that the user can do some actions while the file is downloading.
I used the apache isis CommandExexuteIn:Background action attribute. However, I got an error
"Not an (encodable) value", this is an error thrown by the ScalarValueRenderer class.
This is how my method looks like:
#Action(semantics = SemanticsOf.SAFE,
command = CommandReification.ENABLED)
commandExecuteIn = CommandExecuteIn.BACKGROUND)
public Blob exportViewAsPdf() {
final Contact contact = this;
final String filename = this.businessName + " Contact Details";
final Map<String, Object> parameters = new HashMap<>();
parameters.put("contact", contact);
final String template = templateLoader.buildFromTemplate(Contact.class, "ContactViewTemplate", parameters);
return pdfExporter.exportAsPdf(filename, template);
}
I think the error has something to do with the command not actually invoking the action but returns the persisted background command.
This implementation actually worked on the method where there is no return type. Did I miss something? Or is there a way to implement background command and get the expected results?
interesting use case, but it's not one I anticipated when that part of the framework was implemented, so I'm not surprised it doesn't work. Obviously the error message you are getting here is pretty obscure, so I've raised a
JIRA ticket to see if we could at least improve that.
I'm interested to know in what user experience you think the framework should provide here?
In the Estatio application that we work on (that has driven out many of the features added to the framework over the last few years) we have a somewhat similar requirement to obtain PDFs from a reporting server (which takes 5 to 10 seconds) and then download them. This is for all the tenants in a shopping centre, so there could be 5 to 50 of these to generate in a single go. The design we went with was to move the rendering into a background command (similar to the templateLoader.buildFromTemplate(...) and pdfExporter.exportAsPdf(...) method calls in your code fragment, and to capture the output as a Document, via the document module. We then use the pdfbox addon to stitch all the document PDFs together as a single downloadable PDF for printing.
Hopefully that gives you some ideas of a different way to support your use case
Thx
Dan
I'm trying to write a Java program which allows one user to act as a server and stream their desktop (video & audio), then other users act as clients and watch the live stream of their desktop (similar to Twitch, Webex, Skype screenshare, etc). I am using VLCJ for this, although I have no commitment to using it so if there is a better solution I'm all ears. Here is the code, which is copied from the link I provide below:
package test.java;
import uk.co.caprica.vlcj.discovery.NativeDiscovery;
import uk.co.caprica.vlcj.player.MediaPlayerFactory;
import uk.co.caprica.vlcj.player.headless.HeadlessMediaPlayer;
import test.java.VlcjTest;
/**
* An example of how to stream a media file over HTTP.
* <p>
* The client specifies an MRL of <code>http://127.0.0.1:5555</code>
*/
public class StreamHttp extends VlcjTest {
//when running this it requires an MRL (Media Resource Locator)
//fancy term for saying the file you want to stream. This could be a url to another
//location that streams media or a filepath to a media file you want to stream
//on the system you are running this code on.
public static void main(String[] args) throws Exception {
new NativeDiscovery().discover();
if(args.length != 1) {
System.out.println("Specify a single MRL to stream");
System.exit(1);
}
//the media you are wanting to stream
String media = args[0];
//this is the IP address and port you are wanting to stream at
//this means clients will connect to http://127.0.0.1:5555
//to watch the stream
String options = formatHttpStream("127.0.0.1", 5555);
System.out.println("Streaming '" + media + "' to '" + options + "'");
//this creates a the actual media player that will make calls into the native
//vlc libraries to actually play the media you supplied. It does it in
//a headless fashion, as you are going to stream it over http to be watched
//instead of playing it locally to be watched.
MediaPlayerFactory mediaPlayerFactory = new MediaPlayerFactory(args);
HeadlessMediaPlayer mediaPlayer = mediaPlayerFactory.newHeadlessMediaPlayer();
//this simply starts the player playing the media you gave it
mediaPlayer.playMedia(media, options);
// Don't exit
//basically you don't want the thread to end and kill the player,
//so it just hangs around and waits for it to end.
Thread.currentThread().join();
}
private static String formatHttpStream(String serverAddress, int serverPort) {
StringBuilder sb = new StringBuilder(60);
sb.append(":sout=#duplicate{dst=std{access=http,mux=ts,");
sb.append("dst=");
sb.append(serverAddress);
sb.append(':');
sb.append(serverPort);
sb.append("}}");
return sb.toString();
}
}
I pass "screen://" as a parameter to this program. When I run the code, I get this error message:
[000000000038b250] access_output_http access out: Consider passing --http-host=IP on the command line instead.
[000000001ccaa220] core mux error: cannot add this stream
[000000001cc72100] core decoder error: cannot create packetizer output (RV32)
I tried searching for a solution but all I could find was this:
Video Streaming in vlcj
and although this user had the same error, I couldn't solve my problem from this link, although I did use the StreamHttp code sample from it. I am a relatively inexperienced programmer so if I missed an obvious solution then I apologize. I am using Java 1.8, Windows 7 64 bit.
You need something like this:
String media = "screen://";
String[] options = {
":sout=#transcode{vcodec=FLV1,vb=4096,scale=0.500000}:http{mux=ffmpeg{mux=flv},dst=:5000/"
};
The key things shown here are a "sout" string to transcode the video, then another appended "sout" string to stream (in this case via http).
In this example string, for http streaming only the port (5000, arbitrarily chosen) is specified. No host is specified, so it means localhost. You could have something like "dst=127.0.0.1:8080/" or whatever you need.
You will have to choose/experiment with the specific transcoding/streaming options that you want. There is no one size fits all for those options.
Foot-note:
You can actually use VLC itself to generate this string for you.
Start VLC, then choose the media you want to play.
Instead of pressing "Play", use the widget to select "Stream" instead. This opens the Streaming wizard where you can pick all of your options.
At the end of the wizard, before you start playing, it shows you the string you need.
I use an application (AppWorx! Someone please create this tag!) that allows documentation to be entered about scheduled jobs as html.
I've been trying to create on-call documentation that would have a link something like this:
1 (806) xxx - xxxx
The page is displayed inside the Java app itself, and any link to http:// is opened in the user's browser window. But a tel link like above causes a big error window to pop up that shows the following error:
java.net.MalformedURLException: For input string: "+1806xxxxxxx"
at java.net.URL.<init>(Unknown Source)
at java.net.URL.<init>(Unknown Source)
at java.net.URL.<init>(Unknown Source)
at com.appworx.client.screen.modmgr.M$2.hyperlinkUpdate(NotesPanel.java:191)
at javax.swing.JEditorPane.fireHyperlinkUpdate(Unknown Source)
at javax.swing.text.html.HTMLEditorKit$LinkController.activateLink(Unknown Source)
at javax.swing.text.html.HTMLEditorKit$LinkController.mouseClicked(Unknown Source)
at java.awt.AWTEventMulticaster.mouseClicked(Unknown Source)
Other protocols fail as well (except http). If I have a mailto: link, instead of getting the error as above, it takes me to the domain portion of the email address.
I believe that whatever version of this class that the app was compiled with is several (and maybe many) years old.
Can anyone tell me what the limitations of this class are, or if workarounds exist?
The documentation for Appworx suggests that even http links will not work unless the app is invoked from the jnlp (is this a sandbox thing somehow?). Though on that note, no one here starts the application any other way.
Can anyone tell me what the limitations of this class are?
To give you an idea of how outdated the EditorKit classes are, as of Java 7 HTMLEditorKit "supports HTML version 3.2 (with some extensions), and is migrating toward version 4.0". No surprise then that the URL class (responsible for the MalformedURLException in the trace you posted) supports just the basic protocols, some of which you mentioned above:
Http
Https
Ftp
File
Jar
Can anyone tell me if workarounds exist?
Well, you can get your hands dirty with the code (if you have access to it), use a custom protocol handler and register it. Luckily for you there is one already for the tel protocol courtesy of the J2ME Polish project:
package de.enough.polish.browser.protocols;
import java.io.IOException;
import javax.microedition.io.StreamConnection;
import javax.microedition.midlet.MIDlet;
import de.enough.polish.browser.ProtocolHandler;
/**
* Protocol handler to handle the <code>tel:</code> protocol. This class calls the given phonenumber on MIDP 2.0 phones.
* Example: <a href="tel:+441231234567#22">Call Me</a>
* Note that this handler requires MIDP 2.0 or higher.
* The tel protocol handler allows you to separate the phone number and the dialtone (dtmf) that should be send after
* establishing the phone call using the '#' sign.
*
* This protocol could actually be realized using the ExternalProtocolHandler as well, however in this
* way we can deal post dial tones (DTMF) in a better way - in the HTML code they just need to be
* separated from the phonenumber using a '#'.
*/
public class TelProtocolHandler
extends ProtocolHandler
{
private MIDlet midlet;
/**
* Creates an TellProtocolHandler object using the default "tel" protocol name.
*
* #param midlet the midlet object of the application
*/
public TelProtocolHandler(MIDlet midlet)
{
this( "tel", midlet );
}
/**
* Creates an TelProtocolHandler object using the specified protocol name.
*
* #param protocolName the name of the protocol to handle
* #param midlet the midlet object of the application
*/
public TelProtocolHandler(String protocolName, MIDlet midlet)
{
super( protocolName );
this.midlet = midlet;
}
/* (non-Javadoc)
* #see de.enough.polish.browser.ProtocolHandler#getConnection(java.lang.String)
*/
public StreamConnection getConnection(String url) throws IOException
{
this.midlet.platformRequest( "tel:" + extractMsisdn(url));
return null;
}
/**
* Strips the MSISDN part off an url.
* In contrast to other protocol handlers, the external protocol handler only uses a single colon to
* separate the external protocol from the folllowing protocol, e.g. external:http://www.j2mepolish.org
*
* #param url the url to remove the protocol from
*
* #return the host and part part of the given url
*/
protected String extractMsisdn(String url)
{
String msisdn = url.substring(this.protocolName.length() + 1);
String separator = null;
//#if polish.dtmf.separator:defined
//#= separator = "${polish.dtmf.separator}";
//# if (!separator.equals("#")) {
//# int pos = msisdn.indexOf('#');
//# if (pos != -1) {
//# msisdn = msisdn.substring(0, pos) + separator + msisdn.substring(pos + 1);
//# }
//# }
//#endif
return msisdn;
}
}
Hope that helps!
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 have several finished, older PHP projects with a lot of includes that I would like to document in javadoc/phpDocumentor style.
While working through each file manually and being forced to do a code review alongside the documenting would be the best thing, I am, simply out of time constraints, interested in tools to help me automate the task as much as possible.
The tool I am thinking about would ideally have the following features:
Parse a PHP project tree and tell me where there are undocumented files, classes, and functions/methods (i.e. elements missing the appropriate docblock comment)
Provide a method to half-way easily add the missing docblocks by creating the empty structures and, ideally, opening the file in an editor (internal or external I don't care) so I can put in the description.
Optional:
Automatic recognition of parameter types, return values and such. But that's not really required.
The language in question is PHP, though I could imagine that a C/Java tool might be able to handle PHP files after some tweaking.
Thanks for your great input!
I think PHP_Codesniffer can indicate when there is no docblock -- see the examples of reports on this page (quoting one of those) :
--------------------------------------------------------------------------------
FOUND 5 ERROR(S) AND 1 WARNING(S) AFFECTING 5 LINE(S)
--------------------------------------------------------------------------------
2 | ERROR | Missing file doc comment
20 | ERROR | PHP keywords must be lowercase; expected "false" but found
| | "FALSE"
47 | ERROR | Line not indented correctly; expected 4 spaces but found 1
47 | WARNING | Equals sign not aligned with surrounding assignments
51 | ERROR | Missing function doc comment
88 | ERROR | Line not indented correctly; expected 9 spaces but found 6
--------------------------------------------------------------------------------
I suppose you could use PHP_Codesniffer to at least get a list of all files/classes/methods that don't have a documentation; from what I remember, it can generate XML as output, which would be easier to parse using some automated tool -- that could be the first step of some docblock-generator ;-)
Also, if you are using phpDocumentor to generate the documentation, can this one not report errors for missing blocks ?
After a couple of tests, it can -- for instance, running it on a class-file with not much documentation, with the --undocumentedelements option, such as this :
phpdoc --filename MyClass.php --target doc --undocumentedelements
Gives this in the middle of the output :
Reading file /home/squale/developpement/tests/temp/test-phpdoc/MyClass.php -- Parsing file
WARNING in MyClass.php on line 2: Class "MyClass" has no Class-level DocBlock.
WARNING in MyClass.php on line 2: no #package tag was used in a DocBlock for class MyClass
WARNING in MyClass.php on line 5: Method "__construct" has no method-level DocBlock.
WARNING in MyClass.php on line 16: File "/home/squale/developpement/tests/temp/test-phpdoc/MyClass.php" has no page-level DocBlock, use #package in the first DocBlock to create one
done
But, here, too, even if it's useful as a reporting tool, it's not that helpful when it comes to generating the missing docblocks...
Now, I don't know of any tool that will pre-generate the missing docblocks for you : I generally use PHP_Codesniffer and/or phpDocumentor in my continuous integration mecanism, it reports missing docblocks, and, then, each developper adds what is missing, from his IDE...
... Which works pretty fine : there is generally not more than a couple of missing docblocks every day, so the task can be done by hand (and Eclipse PDT provides a feature to pre-generate the docblock for a method, when you are editing a specific file/method).
Appart from that, I don't really know any fully-automated tool to generate docblocks... But I'm pretty sure we could manage to create an interesting tool, using either :
The Reflection API
token_get_all to parse the source of a PHP file.
After a bit more searching, though, I found this blog-post (it's in french -- maybe some people here will be able to understand) : Ajout automatique de Tags phpDoc à l'aide de PHP_Beautifier.
Possible translation of the title : "Automatically adding phpDoc tags, using PHP_Beautifier"
The idea is actually not bad :
The PHP_Beautifier tool is pretty nice and powerful, when it comes to formating some PHP code that's not well formated
I've used it many times for code that I couldn't even read ^^
And it can be extended, using what it calls "filters".
see PHP_Beautifier_Filter for a list of provided filters
The idea that's used in the blog-post I linked to is to :
create a new PHP_Beautifier filter, that will detect the following tokens :
T_CLASS
T_FUNCTION
T_INTERFACE
And add a "draft" doc-block just before them, if there is not already one
To run the tool on some MyClass.php file, I've had to first install PHP_Beautifier :
pear install --alldeps Php_Beautifier-beta
Then, download the filter to the directory I was working in (could have put it in the default directory, of course) :
wget http://fxnion.free.fr/downloads/phpDoc.filter.phpcs
cp phpDoc.filter.phpcs phpDoc.filter.php
And, after that, I created a new beautifier-1.php script (Based on what's proposed in the blog-post I linked to, once again), which will :
Load the content of my MyClass.php file
Instanciate PHP_Beautifier
Add some filters to beautify the code
Add the phpDoc filter we just downloaded
Beautify the source of our file, and echo it to the standard output.
The code of the beautifier-1.php script will like this :
(Once again, the biggest part is a copy-paste from the blog-post ; I only translated the comments, and changed a couple of small things)
require_once 'PHP/Beautifier.php';
// Load the content of my source-file, with missing docblocks
$sourcecode = file_get_contents('MyClass.php');
$oToken = new PHP_Beautifier();
// The phpDoc.filter.php file is not in the default directory,
// but in the "current" one => we need to add it to the list of
// directories that PHP_Beautifier will search in for filters
$oToken->addFilterDirectory(dirname(__FILE__));
// Adding some nice filters, to format the code
$oToken->addFilter('ArrayNested');
$oToken->addFilter('Lowercase');
$oToken->addFilter('IndentStyles', array('style'=>'k&r'));
// Adding the phpDoc filter, asking it to add a license
// at the beginning of the file
$oToken->addFilter('phpDoc', array('license'=>'php'));
// The code is in $sourceCode
// We could also have used the setInputFile method,
// instead of having the code in a variable
$oToken->setInputString($sourcecode);
$oToken->process();
// And here we get the result, all clean !
echo $oToken->get();
Note that I also had to path two small things in phpDoc.filter.php, to avoid a warning and a notice...
The corresponding patch can be downloaded there : http://extern.pascal-martin.fr/so/phpDoc.filter-pmn.patch
Now, if we run that beautifier-1.php script :
$ php ./beautifier-1.php
With a MyClass.php file that initialy contains this code :
class MyClass {
public function __construct($myString, $myInt) {
//
}
/**
* Method with some comment
* #param array $params blah blah
*/
public function doSomething(array $params = array()) {
// ...
}
protected $_myVar;
}
Here's the kind of result we get -- once our file is Beautified :
<?php
/**
*
* PHP version 5
*
* LICENSE: This source file is subject to version 3.0 of the PHP license
* that is available through the world-wide-web at the following URI:
* http://www.php.net/license/3_0.txt. If you did not receive a copy of
* the PHP License and are unable to obtain it through the web, please
* send a note to license#php.net so we can mail you a copy immediately.
* #category PHP
* #package
* #subpackage Filter
* #author FirstName LastName <mail>
* #copyright 2009 FirstName LastName
* #link
* #license http://www.php.net/license/3_0.txt PHP License 3.0
* #version CVS: $Id:$
*/
/**
* #todo Description of class MyClass
* #author
* #version
* #package
* #subpackage
* #category
* #link
*/
class MyClass {
/**
* #todo Description of function __construct
* #param $myString
* #param $myInt
* #return
*/
public function __construct($myString, $myInt) {
//
}
/**
* Method with some comment
* #param array $params blah blah
*/
public function doSomething(array $params = array()) {
// ...
}
protected $_myVar;
}
We can note :
The license block at the beginning of the file
The docblock that's been added on the MyClass class
The docblock that's been added on the __construct method
The docblock on the doSomething was already present in our code : it's not been removed.
There are some #todo tags ^^
Now, it's not perfect, of course :
It doesn't document all the stuff we could want it too
For instance, here, it didn't document the protected $_myVar
It doesn't enhance existing docblocks
And it doesn't open the file in any graphical editor
But that would be much harder, I guess...
But I'm pretty sure that this idea could be used as a starting point to something a lot more interesting :
About the stuff that doesn't get documented : adding new tags that will be recognized should not be too hard
You just have to add them to a list at the beginning of the filter
Enhancing existing docblocks might be harder, I have to admit
A nice thing is this could be fully-automated
Using Eclipse PDT, maybe this could be set as an External Tool, so we can at least launch it from our IDE ?
Since PHPCS was already mentioned, I throw in the Reflection API to check for missing DocBlocks. The article linked below is a short tutorial on how you could approach your problem:
http://www.phpriot.com/articles/reflection-api
There is also a PEAR Package PHP_DocBlockGenerator that can Create the file Page block and the DocBlocks for includes, global variables, functions, parameters, classes, constants, properties and methods (and other things).
php-tracer-weaver can instrument code and generate docblocks with the parameter types, deducted through runtime analysis.
You can use the Code Sniffer for PHP to test your code against a predefined set of coding guidelines. It will also check for missing docblocks and generate a report you can use to identify the files.
The 1.4.x versions of phpDocumentor have the -ue option (--undocumentedelements) [1], which will cause undocumented elements to be listed as warnings on the errors.html page that it generates during its doc run.
Further, PHP_DocBlockGenerator [2] from PEAR looks like it can generate missing docblocks for you.
[1] -- http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#using.command-line.undocumentedelements
[2] -- http://pear.php.net/package/PHP_DocBlockGenerator
We use codesniffer for this functionality at work, using standard PEAR or Zend standards. It will not allow you to edit the files on the fly, but will definitely give you a list, with lines and description of what kind of docblock is missing.
HTH,
Jc
No idea if it's any help, but if Codesniffer can point out the functions/methods, then a decent PHP IDE (I offer PHPEd) can easily inspect and scaffold the PHPDoc comments for each function.
Simply type /** above each function and press ENTER, and PHPEd will auto-complete the code with #param1, #param1, #return, etc. filled out correctly, ready for your extra descriptions. Here's the first one I tried in order to provide an example:
/**
* put your comment here...
*
* #param mixed $url
* #param mixed $method
* #param mixed $timeout
* #param mixed $vars
* #param mixed $allow_redirects
* #return mixed
*/
public static function curl_get_file_contents($url, $method = 'get', $timeout = 30, $vars = array(), $allow_redirects = true)
This is easily tweaked to:
/**
* Retrieves a file using the cURL extension
*
* #param string $url
* #param string $method
* #param int $timeout
* #param array $vars parameters to pass to cURL
* #param int $allow_redirects boolean choice to follow any redirects $url serves up
* #return mixed
*/
public static function curl_get_file_contents($url, $method = 'get', $timeout = 30, $vars = array(), $allow_redirects = true)
Not exactly an automated solution, but quick enough for me as a lazy developer :)
You want to actually automate the problem of filling in the "javadoc" type data?
The DMS Software Reengineering Toolkit could be configured to do this.
It parses source text just like compilers do, builds internal compiler structures, lets you implement arbitrary analyses, make modification to those structures, and then regenerate ("prettyprint") the source text changed according to the structure changes. It even preserves comments and formatting of the original text; you can of course insert additional comments and they will appear and this seems to be your primary goal. DMS does this for many languages, including PHP
What you would want to do is parse each PHP file, locate every class/method, generate the "javadoc" comments that should be that entity (difference for classes and methods, right?) and then check that corresponding comments were actually present in the compiler structures. If not, simply insert them. PrettyPrint the final result.
Because it has access to the compiler structures that represent the code, it shouldn't be difficult to generate parameter and return info, as you suggested. What it can't do, of course, is generate comments about intendend purpose; but it could generate a placeholder for you to fill in later.
I had to do a large batch of automation of docblock fixing recently, mostly based on the correct answer above kwith some context-specific changes. It's a hack, but I'm linking back here in case it's useful to anyone else in the future. Essentially, it does basic parsing on comment block tokens within PHP Beautifier.
https://gist.github.com/israelshirk/408f2656100196e73367